@agent-native/core 0.107.2 → 0.109.0

package/corpus/templates/slides/actions/search-images.ts

@@ -1,55 +1,27 @@
 import { defineAction } from "@agent-native/core";
-import { resolveSecret } from "@agent-native/core/server";
 import { z } from "zod";
 
+import { searchProviderImages } from "../server/lib/media-search-providers.js";
+
 export default defineAction({
   description: "Search for images using Google Custom Search API.",
   schema: z.object({
     q: z.string().optional().describe("Search query (required)"),
+    count: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .default(10)
+      .describe("Maximum number of image results to return."),
   }),
   http: { method: "GET" },
+  readOnly: true,
   run: async (args) => {
     const q = args.q;
     if (!q) {
       throw new Error("Missing query parameter 'q'");
     }
-
-    const [apiKey, cx] = await Promise.all([
-      resolveSecret("GOOGLE_API_KEY"),
-      resolveSecret("GOOGLE_SEARCH_CX"),
-    ]);
-
-    if (!apiKey || !cx) {
-      throw new Error(
-        "Google Search not configured. Save GOOGLE_API_KEY and GOOGLE_SEARCH_CX in settings.",
-      );
-    }
-
-    const params = new URLSearchParams({
-      key: apiKey,
-      cx,
-      q,
-      searchType: "image",
-      num: "10",
-      safe: "active",
-    });
-
-    const response = await fetch(
-      `https://www.googleapis.com/customsearch/v1?${params}`,
-    );
-    if (!response.ok) {
-      const text = await response.text();
-      console.error("Google API error:", response.status, text);
-      throw new Error("Google API error");
-    }
-
-    const data = await response.json();
-    return (data.items || []).map((item: any) => ({
-      url: item.link,
-      thumbnail: item.image?.thumbnailLink || item.link,
-      title: item.title,
-      width: item.image?.width,
-      height: item.image?.height,
-    }));
+    return searchProviderImages(q, args.count);
   },
 });

package/corpus/templates/slides/actions/search-logos.ts

@@ -1,67 +1,20 @@
 import { defineAction } from "@agent-native/core";
 import { z } from "zod";
 
+import { searchProviderLogos } from "../server/lib/media-search-providers.js";
+
 export default defineAction({
   description: "Search for company logos by name or domain.",
   schema: z.object({
     q: z.string().optional().describe("Company name or domain to search"),
   }),
   http: { method: "GET" },
+  readOnly: true,
   run: async (args) => {
-    const q = (args.q || "").trim().toLowerCase();
+    const q = (args.q || "").trim();
     if (!q) {
       throw new Error("Missing ?q= parameter");
     }
-
-    const secretKey = process.env.LOGO_DEV_SECRET_KEY;
-
-    // If we have a secret key that's actually an sk_ key, use the search API
-    if (secretKey && secretKey.startsWith("sk_")) {
-      try {
-        const response = await fetch(
-          `https://api.logo.dev/search?q=${encodeURIComponent(q)}`,
-          { headers: { Authorization: `Bearer ${secretKey}` } },
-        );
-
-        if (response.ok) {
-          const results: Array<{ name: string; domain: string }> =
-            await response.json();
-          return results.map((r) => ({ name: r.name, domain: r.domain }));
-        }
-      } catch {
-        // Fall through to domain guessing
-      }
-    }
-
-    // Domain guessing: generate candidate domains from the query
-    const candidates: Array<{ name: string; domain: string }> = [];
-
-    if (q.includes(".")) {
-      const clean = q
-        .replace(/^https?:\/\//, "")
-        .replace(/^www\./, "")
-        .split("/")[0];
-      candidates.push({ name: clean.split(".")[0], domain: clean });
-    } else {
-      const slug = q.replace(/[^a-z0-9]/g, "");
-      const slugDashed = q.replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-
-      const tlds = [".com", ".io", ".co", ".dev", ".org", ".net"];
-      const seen = new Set<string>();
-
-      for (const tld of tlds) {
-        const domain = slug + tld;
-        if (!seen.has(domain)) {
-          seen.add(domain);
-          candidates.push({ name: q, domain });
-        }
-      }
-
-      if (slugDashed !== slug) {
-        candidates.push({ name: q, domain: slugDashed + ".com" });
-      }
-    }
-
-    return candidates;
+    return searchProviderLogos(q);
   },
 });

package/corpus/templates/slides/app/components/editor/ImageSearchPanel.tsx

@@ -61,7 +61,7 @@ export default function ImageSearchPanel({
     setLoading(true);
     setError(null);
     try {
-      const data = await callAction<SearchResult[]>(
+      const data = await callAction(
         "search-images",
         { q: query.trim() },
         { method: "GET" },

package/corpus/templates/slides/app/components/editor/LogoSearchPanel.tsx

@@ -1,17 +1,12 @@
-import {
-  agentNativePath,
-  useActionQuery,
-  useT,
-} from "@agent-native/core/client";
+import { callAction, useActionQuery, useT } from "@agent-native/core/client";
 import { IconX, IconSearch, IconLoader2 } from "@tabler/icons-react";
 import { useState, useEffect, useRef } from "react";
 import { createPortal } from "react-dom";
 
-const LOGO_DEV_PK = "pk_VwOyCAOgT0aBNpecT2qO-A";
-
 interface LogoResult {
   name: string;
   domain: string;
+  logoUrl?: string;
 }
 
 interface LogoSearchPanelProps {
@@ -32,6 +27,7 @@ export default function LogoSearchPanel({
   const [error, setError] = useState<string | null>(null);
   const [selectedDomain, setSelectedDomain] = useState<string | null>(null);
   const [brandfetchId, setBrandfetchId] = useState<string | null>(null);
+  const [logoDevToken, setLogoDevToken] = useState<string | null>(null);
   const panelRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
 
@@ -41,6 +37,7 @@ export default function LogoSearchPanel({
     if (logoConfigData?.brandfetchId) {
       setBrandfetchId(logoConfigData.brandfetchId);
     }
+    setLogoDevToken(logoConfigData?.logoDevToken ?? null);
   }, [logoConfigData]);
 
   useEffect(() => {
@@ -84,17 +81,7 @@ export default function LogoSearchPanel({
     setResults([]);
     setSelectedDomain(null);
     try {
-      const res = await fetch(
-        agentNativePath(
-          `/_agent-native/actions/search-logos?q=${encodeURIComponent(q)}`,
-        ),
-      );
-      if (!res.ok) {
-        const data = await res.json();
-        setError(data.error || "Search failed");
-        return;
-      }
-      const data: LogoResult[] = await res.json();
+      const data = await callAction("search-logos", { q }, { method: "GET" });
       if (data.length === 0) {
         setError("No logos found");
       } else {
@@ -116,7 +103,7 @@ export default function LogoSearchPanel({
 
   // Build variations for the selected domain
   const variations = selectedDomain
-    ? buildVariations(selectedDomain, brandfetchId, t)
+    ? buildVariations(selectedDomain, brandfetchId, logoDevToken, t)
     : [];
 
   return createPortal(
@@ -323,14 +310,12 @@ interface VariationGroup {
 function buildVariations(
   domain: string,
   _brandfetchId: string | null,
+  logoDevToken: string | null,
   t: ReturnType<typeof useT>,
 ): VariationGroup[] {
   // Brandfetch CDN works without client ID for free tier
   const bf = (path: string) => `https://cdn.brandfetch.io/${domain}/${path}`;
-  const ld = (params: string) =>
-    `https://img.logo.dev/${domain}?token=${LOGO_DEV_PK}&${params}`;
-
-  return [
+  const groups: VariationGroup[] = [
     {
       label: "Logo",
       items: [
@@ -355,7 +340,11 @@ function buildVariations(
         { label: "Icon", url: bf("icon.png"), bg: "rgba(255,255,255,0.03)" },
       ],
     },
-    {
+  ];
+  if (logoDevToken) {
+    const ld = (params: string) =>
+      `https://img.logo.dev/${domain}?token=${encodeURIComponent(logoDevToken)}&${params}`;
+    groups.push({
       label: "Logo.dev",
       items: [
         {
@@ -374,6 +363,7 @@ function buildVariations(
           bg: "rgba(255,255,255,0.03)",
         },
       ],
-    },
-  ];
+    });
+  }
+  return groups;
 }

package/corpus/templates/slides/app/entry.client.tsx

@@ -1,7 +1,12 @@
-import { appBasePath } from "@agent-native/core/client/api-path";
+import {
+  appBasePath,
+  installRouteChunkRecovery,
+} from "@agent-native/core/client";
 import { hydrateRoot } from "react-dom/client";
 import { HydratedRouter } from "react-router/dom";
 
+installRouteChunkRecovery();
+
 const basePath = appBasePath();
 const pathname = window.location.pathname;
 const routerBasePath =

package/corpus/templates/slides/server/lib/media-search-providers.ts

@@ -0,0 +1,216 @@
+import { resolveSecret } from "@agent-native/core/server";
+
+const GOOGLE_IMAGE_SEARCH_URL = "https://www.googleapis.com/customsearch/v1";
+const LOGO_DEV_SEARCH_URL = "https://api.logo.dev/search";
+const PROVIDER_TIMEOUT_MS = 15_000;
+
+export interface ImageSearchResult {
+  url: string;
+  thumbnail: string;
+  title: string;
+  width?: number;
+  height?: number;
+}
+
+export interface LogoSearchResult {
+  name: string;
+  domain: string;
+  logoUrl: string;
+  source: "logo.dev" | "domain-guess";
+}
+
+export interface MediaSearchRuntime {
+  resolveSecret: (key: string) => Promise<string | null | undefined>;
+  fetch: typeof fetch;
+}
+
+const defaultRuntime: MediaSearchRuntime = {
+  resolveSecret,
+  fetch: (...args) => fetch(...args),
+};
+
+function fetchOptions(init: RequestInit = {}): RequestInit {
+  return {
+    ...init,
+    signal: init.signal ?? AbortSignal.timeout(PROVIDER_TIMEOUT_MS),
+  };
+}
+
+function normalizedDomain(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, "")
+    .replace(/^www\./, "")
+    .split("/", 1)[0]!
+    .replace(/[^a-z0-9.-]/g, "");
+}
+
+function logoResult(
+  name: string,
+  domain: string,
+  source: LogoSearchResult["source"],
+): LogoSearchResult | null {
+  const normalized = normalizedDomain(domain);
+  if (!normalized || !normalized.includes(".")) return null;
+  return {
+    name: name.trim() || normalized.split(".")[0] || normalized,
+    domain: normalized,
+    logoUrl: `https://cdn.brandfetch.io/${normalized}/logo.png`,
+    source,
+  };
+}
+
+function guessedLogoDomains(query: string): LogoSearchResult[] {
+  const normalized = normalizedDomain(query);
+  if (normalized.includes(".")) {
+    const result = logoResult(
+      normalized.split(".")[0] ?? normalized,
+      normalized,
+      "domain-guess",
+    );
+    return result ? [result] : [];
+  }
+
+  const compact = query.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const dashed = query
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+  if (!compact) return [];
+
+  const candidates = [
+    ...["com", "io", "co", "dev", "org", "net"].map(
+      (tld) => `${compact}.${tld}`,
+    ),
+    ...(dashed && dashed !== compact ? [`${dashed}.com`] : []),
+  ];
+  return candidates.flatMap((domain) => {
+    const result = logoResult(query, domain, "domain-guess");
+    return result ? [result] : [];
+  });
+}
+
+export async function searchProviderImages(
+  query: string,
+  count = 10,
+  runtime: MediaSearchRuntime = defaultRuntime,
+): Promise<ImageSearchResult[]> {
+  const normalizedQuery = query.trim();
+  if (!normalizedQuery) throw new Error("Image search requires a query.");
+
+  const [apiKey, searchEngineId] = await Promise.all([
+    runtime.resolveSecret("GOOGLE_API_KEY"),
+    runtime.resolveSecret("GOOGLE_SEARCH_CX"),
+  ]);
+  if (!apiKey || !searchEngineId) {
+    throw new Error(
+      "Google Search not configured. Save GOOGLE_API_KEY and GOOGLE_SEARCH_CX in settings.",
+    );
+  }
+
+  const params = new URLSearchParams({
+    key: apiKey,
+    cx: searchEngineId,
+    q: normalizedQuery,
+    searchType: "image",
+    num: String(Math.max(1, Math.min(Math.floor(count), 10))),
+    safe: "active",
+  });
+  const response = await runtime.fetch(
+    `${GOOGLE_IMAGE_SEARCH_URL}?${params}`,
+    fetchOptions(),
+  );
+  if (!response.ok) {
+    throw new Error(`Google image search failed (${response.status}).`);
+  }
+
+  const data = (await response.json()) as {
+    items?: Array<{
+      link?: unknown;
+      title?: unknown;
+      image?: {
+        width?: unknown;
+        height?: unknown;
+        thumbnailLink?: unknown;
+      };
+    }>;
+  };
+  return (data.items ?? []).flatMap((item) => {
+    if (typeof item.link !== "string" || !item.link) return [];
+    const thumbnail =
+      typeof item.image?.thumbnailLink === "string"
+        ? item.image.thumbnailLink
+        : item.link;
+    return [
+      {
+        url: item.link,
+        thumbnail,
+        title: typeof item.title === "string" ? item.title : "Untitled image",
+        ...(typeof item.image?.width === "number"
+          ? { width: item.image.width }
+          : {}),
+        ...(typeof item.image?.height === "number"
+          ? { height: item.image.height }
+          : {}),
+      },
+    ];
+  });
+}
+
+export async function searchProviderLogos(
+  query: string,
+  runtime: MediaSearchRuntime = defaultRuntime,
+): Promise<LogoSearchResult[]> {
+  const normalizedQuery = query.trim();
+  if (!normalizedQuery) throw new Error("Logo search requires a query.");
+
+  const secretKey = await runtime.resolveSecret("LOGO_DEV_SECRET_KEY");
+  if (secretKey?.startsWith("sk_")) {
+    try {
+      const url = new URL(LOGO_DEV_SEARCH_URL);
+      url.searchParams.set("q", normalizedQuery);
+      const response = await runtime.fetch(
+        url,
+        fetchOptions({
+          headers: { Authorization: `Bearer ${secretKey}` },
+        }),
+      );
+      if (response.ok) {
+        const data = (await response.json()) as Array<{
+          name?: unknown;
+          domain?: unknown;
+        }>;
+        const results = data.flatMap((item) => {
+          if (typeof item.domain !== "string") return [];
+          const result = logoResult(
+            typeof item.name === "string" ? item.name : normalizedQuery,
+            item.domain,
+            "logo.dev",
+          );
+          return result ? [result] : [];
+        });
+        if (results.length > 0) return results;
+      }
+    } catch {
+      // The deterministic domain fallback keeps the UI usable during provider outages.
+    }
+  }
+
+  return guessedLogoDomains(normalizedQuery);
+}
+
+export async function getLogoProviderConfig(
+  runtime: MediaSearchRuntime = defaultRuntime,
+) {
+  const [brandfetchId, logoDevToken, logoDevSecret] = await Promise.all([
+    runtime.resolveSecret("BRANDFETCH_CLIENT_ID"),
+    runtime.resolveSecret("LOGO_DEV_TOKEN"),
+    runtime.resolveSecret("LOGO_DEV_SECRET_KEY"),
+  ]);
+  return {
+    brandfetchId: brandfetchId || null,
+    logoDevToken: logoDevToken?.startsWith("pk_") ? logoDevToken : null,
+    hasLogoDevSecret: logoDevSecret?.startsWith("sk_") === true,
+  };
+}

package/corpus/templates/slides/server/register-secrets.ts

@@ -94,6 +94,36 @@ registerRequiredSecret({
   required: false,
 });
 
+registerRequiredSecret({
+  key: "LOGO_DEV_SECRET_KEY",
+  label: "Logo.dev Search Key",
+  description: "Optional server-side key for company and domain logo search.",
+  docsUrl: "https://www.logo.dev/",
+  scope: "user",
+  kind: "api-key",
+  required: false,
+});
+
+registerRequiredSecret({
+  key: "LOGO_DEV_TOKEN",
+  label: "Logo.dev Publishable Token",
+  description: "Optional publishable token for rendering Logo.dev images.",
+  docsUrl: "https://www.logo.dev/",
+  scope: "user",
+  kind: "api-key",
+  required: false,
+});
+
+registerRequiredSecret({
+  key: "BRANDFETCH_CLIENT_ID",
+  label: "Brandfetch Client ID",
+  description: "Optional public client ID for Brandfetch logo rendering.",
+  docsUrl: "https://developers.brandfetch.com/",
+  scope: "user",
+  kind: "api-key",
+  required: false,
+});
+
 registerRequiredSecret({
   key: "GOOGLE_CLIENT_ID",
   label: "Google OAuth Client ID",

package/corpus/templates/tasks/.agents/skills/feature-flags/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: feature-flags
+description: >-
+  Declare, evaluate, manage, and remove framework feature flags. Use when
+  shipping a capability gradually, targeting users or organizations, or
+  replacing a compile-time rollout switch with a production-safe runtime flag.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Feature Flags
+
+A feature flag is a boolean declared in app code, evaluated locally by Core,
+and managed from the Analytics fleet control plane. Code owns whether a flag
+exists. Runtime settings own only its rollout state.
+
+Flags let an app deploy dormant code and turn it on in the real environment
+without another deployment. They are not experiments: do not add variants,
+hypotheses, conversion metrics, exposure tracking, or lifecycle states.
+
+## When to use one
+
+Use a flag for a reversible rollout of a user-facing capability whose dormant
+code is safe to deploy. Flags are useful for production dogfooding, exact-user
+or organization pilots, and deterministic percentage rollouts.
+
+Do not use a flag for authentication, authorization, secrets, audit enablement,
+SSR cache behavior, or another security boundary. Client hiding is presentation
+only; every guarded server action must evaluate the same registered flag.
+
+## Agent workflow
+
+### 1. Declare
+
+Keep definitions in a shared TypeScript module so server and client code use the
+same stable key. Flags are boolean and default-off.
+
+```ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+Keys are immutable, never reused, and contain only letters, numbers, dots,
+underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
+definitions or rollout rows from Analytics.
+
+### 2. Register
+
+Register app definitions from a Nitro plugin before actions are discovered.
+Do not add app-specific flags to a Core registry.
+
+```ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+### 3. Guard server and client
+
+The server action is the enforcement boundary:
+
+```ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // guarded operation
+}
+```
+
+Use the client hook only to hide or reveal hydrated UI:
+
+```tsx
+import { useFeatureFlag } from "@agent-native/core/client";
+
+const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+return enabled ? <FullAppOption /> : null;
+```
+
+The client hook intentionally returns false while loading or for an unknown
+flag. Never replace that fail-closed behavior with app-local bucketing or a
+compile-time fallback. Never evaluate personalized flags in the public SSR
+shell; it is shared and cached for every visitor.
+
+### 4. Verify and roll out
+
+1. Verify the off path before changing rollout state.
+2. Confirm the registered flag appears in **Analytics → Feature flags** for the
+   app and is Off by default.
+3. Use **Enable for me** for initial production dogfood.
+4. Expand to exact emails, organization IDs, or a percentage only from
+   Analytics.
+5. Confirm the client presentation and authoritative server action agree.
+
+## Management contract
+
+Core mounts three actions in registered apps:
+
+| Action | Purpose |
+| --- | --- |
+| `get-feature-flags` | Return the current caller's evaluated boolean values. |
+| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
+| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
+
+Analytics calls the app-local operator actions through narrowly scoped A2A
+delegation. Tokens require an exact audience, organization, scope, operator
+role, and audit correlation id. Management is permission-checked and audited
+by the target app. Never manage flags through generic settings routes, raw SQL,
+or per-app toggle UIs.
+
+## Rollout semantics
+
+The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
+as `off`, `rules`, and `on`.
+
+Targeted rules combine exact normalized emails, exact organization IDs, and a
+percentage with OR semantics. Exact matches are checked first. Percentage
+buckets use Core's stable hash of the flag key and authenticated user identity;
+anonymous callers fail closed. Raising a percentage preserves the users already
+included at a lower percentage. Do not implement bucketing in app code.
+
+Unknown definitions, missing state, malformed state, storage errors, and
+evaluation errors all return the code default (`false` in v1). Explicit Off
+wins over every target; Everyone enables every authenticated caller.
+
+## Remove a flag
+
+After a rollout is permanent:
+
+1. Replace guarded branches with the chosen behavior.
+2. Delete the server and client gates.
+3. Delete the definition and registration entry.
+4. Verify the flag disappears from the Analytics fleet.
+5. Remove stale tests and rollout instructions.
+
+A permanent flag is just an if statement with a pension plan.
+
+## Verification checklist
+
+- Unknown and unregistered keys evaluate false.
+- UI hiding and server enforcement use the same registered key.
+- Exact-user, organization, deterministic percentage, Everyone, and Off paths
+  have focused tests.
+- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
+- Unauthorized callers cannot list targeting details or mutate flags.
+- Mutations are atomic, read back stored state, emit refresh, and appear in the
+  audit log with the flag key.
+- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
+  and unreachable directory apps honestly.
+- Future agents can find this skill from root `AGENTS.md`, and
+  `pnpm guard:workspace-skills` passes after syncing generated copies.
+
+## Related skills
+
+- **adding-a-feature** — preserve UI/action/instruction/application-state parity
+- **actions** — define and call guarded app operations
+- **audit-log** — inspect automatic action mutation history
+- **reliable-mutations** — make rollout changes atomic and provable
+- **security** — keep security controls out of feature flags