@agent-native/core 0.80.11 → 0.81.0

package/corpus/templates/design/actions/list-figma-library-assets.ts

@@ -0,0 +1,292 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { executeProviderApiRequest } from "../server/lib/provider-api.js";
+
+const FIGMA_FILE_KEY_RE = /^[A-Za-z0-9_-]{8,}$/;
+
+const FigmaRenderFormatSchema = z.enum(["svg", "png"]).default("svg");
+
+const schemaInput = z
+  .object({
+    fileUrl: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Figma file URL, for example https://www.figma.com/design/<fileKey>/...",
+      ),
+    fileKey: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Figma file key. Used when fileUrl is omitted."),
+    query: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Optional case-insensitive search over names/descriptions."),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(64)
+      .default(48)
+      .describe("Maximum number of Figma library assets to return."),
+    renderFormat: FigmaRenderFormatSchema.describe(
+      "Image format for insertable render URLs.",
+    ),
+  })
+  .refine((value) => value.fileUrl || value.fileKey, {
+    message: "Pass fileUrl or fileKey.",
+    path: ["fileUrl"],
+  });
+
+type FigmaProviderEnvelope = {
+  response?: {
+    ok?: boolean;
+    status?: number;
+    statusText?: string;
+    json?: unknown;
+    text?: string;
+  };
+};
+
+type FigmaAssetKind = "component" | "component_set";
+
+type FigmaComponentRecord = {
+  key?: unknown;
+  file_key?: unknown;
+  node_id?: unknown;
+  name?: unknown;
+  description?: unknown;
+  thumbnail_url?: unknown;
+  created_at?: unknown;
+  updated_at?: unknown;
+  containing_frame?: unknown;
+  user?: unknown;
+};
+
+type FigmaImageResponse = {
+  images?: Record<string, string | null | undefined>;
+};
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function numberOrDefault(value: number | undefined, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+export function parseFigmaFileKey(input: string | undefined): string | null {
+  const value = input?.trim();
+  if (!value) return null;
+  if (FIGMA_FILE_KEY_RE.test(value)) return value;
+
+  try {
+    const url = new URL(value);
+    const parts = url.pathname.split("/").filter(Boolean);
+    for (const segment of ["design", "file", "proto"]) {
+      const index = parts.indexOf(segment);
+      if (index >= 0) {
+        const candidate = parts[index + 1];
+        if (candidate && FIGMA_FILE_KEY_RE.test(candidate)) return candidate;
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+function figmaNodeUrl(
+  fileKey: string,
+  nodeId: string,
+  fileUrl?: string,
+): string {
+  const nodeParam = nodeId.replace(/:/g, "-");
+  try {
+    const url = new URL(fileUrl || `https://www.figma.com/design/${fileKey}`);
+    url.searchParams.set("node-id", nodeParam);
+    return url.href;
+  } catch {
+    return `https://www.figma.com/design/${fileKey}?node-id=${encodeURIComponent(
+      nodeParam,
+    )}`;
+  }
+}
+
+function recordSearchText(record: FigmaComponentRecord): string {
+  const frame =
+    record.containing_frame &&
+    typeof record.containing_frame === "object" &&
+    "name" in record.containing_frame
+      ? stringValue((record.containing_frame as { name?: unknown }).name)
+      : null;
+  return [stringValue(record.name), stringValue(record.description), frame]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+}
+
+function matchesQuery(record: FigmaComponentRecord, query: string | undefined) {
+  const normalized = query?.trim().toLowerCase();
+  if (!normalized) return true;
+  return recordSearchText(record).includes(normalized);
+}
+
+function normalizeFigmaRecords(
+  value: unknown,
+  kind: FigmaAssetKind,
+): FigmaComponentRecord[] {
+  if (!value || typeof value !== "object") return [];
+  const meta = (value as { meta?: unknown }).meta;
+  const key = kind === "component" ? "components" : "component_sets";
+  const records =
+    meta && typeof meta === "object"
+      ? (meta as Record<string, unknown>)[key]
+      : undefined;
+  if (!Array.isArray(records)) return [];
+  return records.filter(
+    (record): record is FigmaComponentRecord =>
+      !!record && typeof record === "object",
+  );
+}
+
+function providerJson(envelope: unknown, label: string): unknown {
+  const response = (envelope as FigmaProviderEnvelope | null)?.response;
+  if (!response) throw new Error(`Figma ${label} response was empty.`);
+  if (response.ok === false) {
+    const detail =
+      stringValue(response.text) ||
+      response.statusText ||
+      `HTTP ${response.status ?? "error"}`;
+    throw new Error(`Figma ${label} request failed: ${detail}`);
+  }
+  return response.json;
+}
+
+async function figmaGet(path: string, query?: Record<string, unknown>) {
+  return executeProviderApiRequest({
+    provider: "figma",
+    method: "GET",
+    path,
+    query,
+    maxBytes: 2 * 1024 * 1024,
+  });
+}
+
+export default defineAction({
+  description:
+    "List reusable assets from a Figma file for the Design asset panel. Returns components and component sets with thumbnails, insertable render URLs, and source provenance. Requires a saved FIGMA_ACCESS_TOKEN secret.",
+  schema: schemaInput,
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    const fileKey =
+      parseFigmaFileKey(args.fileKey) ?? parseFigmaFileKey(args.fileUrl);
+    if (!fileKey) {
+      throw new Error("Could not find a Figma file key in the provided URL.");
+    }
+
+    const limit = numberOrDefault(args.limit, 48);
+    const [componentsEnvelope, componentSetsEnvelope] = await Promise.all([
+      figmaGet(`/files/${fileKey}/components`),
+      figmaGet(`/files/${fileKey}/component_sets`),
+    ]);
+    const componentRecords = normalizeFigmaRecords(
+      providerJson(componentsEnvelope, "components"),
+      "component",
+    )
+      .filter((record) => matchesQuery(record, args.query))
+      .map((record) => ({ kind: "component" as const, record }));
+    const componentSetRecords = normalizeFigmaRecords(
+      providerJson(componentSetsEnvelope, "component sets"),
+      "component_set",
+    )
+      .filter((record) => matchesQuery(record, args.query))
+      .map((record) => ({ kind: "component_set" as const, record }));
+
+    const rawItems = [...componentRecords, ...componentSetRecords].slice(
+      0,
+      limit,
+    );
+    const renderIds = rawItems
+      .map((item) => stringValue(item.record.node_id))
+      .filter((id): id is string => !!id);
+    let rendered: Record<string, string | null | undefined> = {};
+    if (renderIds.length > 0) {
+      const imagesEnvelope = await figmaGet(`/images/${fileKey}`, {
+        ids: renderIds.join(","),
+        format: args.renderFormat,
+        svg_include_id: true,
+      });
+      const images = providerJson(
+        imagesEnvelope,
+        "images",
+      ) as FigmaImageResponse;
+      rendered = images.images ?? {};
+    }
+
+    const assets = rawItems
+      .map(({ kind, record }) => {
+        const nodeId = stringValue(record.node_id);
+        const key = stringValue(record.key);
+        const name = stringValue(record.name) ?? "Untitled Figma asset";
+        const description = stringValue(record.description);
+        const thumbnailUrl = stringValue(record.thumbnail_url);
+        const renderUrl = nodeId ? stringValue(rendered[nodeId]) : null;
+        const containingFrame =
+          record.containing_frame && typeof record.containing_frame === "object"
+            ? {
+                name:
+                  stringValue(
+                    (record.containing_frame as { name?: unknown }).name,
+                  ) ?? null,
+                nodeId:
+                  stringValue(
+                    (record.containing_frame as { nodeId?: unknown }).nodeId,
+                  ) ??
+                  stringValue(
+                    (record.containing_frame as { node_id?: unknown }).node_id,
+                  ),
+              }
+            : null;
+
+        return {
+          id: `figma:${fileKey}:${nodeId ?? key ?? name}`,
+          kind,
+          fileKey,
+          nodeId,
+          componentKey: key,
+          name,
+          description,
+          thumbnailUrl,
+          renderUrl,
+          insertUrl: renderUrl ?? thumbnailUrl,
+          sourceUrl: nodeId
+            ? figmaNodeUrl(fileKey, nodeId, args.fileUrl)
+            : null,
+          containingFrame,
+          createdAt: stringValue(record.created_at),
+          updatedAt: stringValue(record.updated_at),
+        };
+      })
+      .filter((asset) => asset.nodeId || asset.componentKey);
+
+    return {
+      source: "figma",
+      fileKey,
+      query: args.query ?? null,
+      renderFormat: args.renderFormat,
+      total: componentRecords.length + componentSetRecords.length,
+      returned: assets.length,
+      assets,
+      guidance:
+        "Use renderUrl/insertUrl with insert-asset and preserve fileKey, nodeId, componentKey, and sourceUrl for provenance. Components/component sets are reusable Figma library assets; styles and variables belong in design-system token sync.",
+    };
+  },
+});

package/corpus/templates/design/actions/migrate-board-objects-to-file.ts

@@ -0,0 +1,238 @@
+/**
+ * migrate-board-objects-to-file
+ *
+ * Lazy, idempotent migration that converts the legacy designs.data.boardObjects
+ * JSON blob into the new board file architecture.
+ *
+ * ## What it does
+ *
+ * 1. Guards on boardFileId already set — returns early if the migration has
+ *    already run (idempotent).
+ * 2. Reads designs.data.boardObjects and converts each entry into an HTML
+ *    fragment via boardObjectEntryToHtmlFragment, preserving negative left/top
+ *    coordinates exactly (no clamping).
+ * 3. Inserts the fragments as direct <body> children of a new __board__.html
+ *    design file (or merges into an existing one if somehow already present).
+ * 4. Stores the new file's id into designs.data.boardFileId in a transaction.
+ * 5. Nulls out designs.data.boardObjects so the old model no longer conflicts.
+ *
+ * ## Contract
+ *
+ * - Requires editor access on the design.
+ * - SCHEMA ADDITIVE ONLY — no columns are dropped or renamed; only designs.data
+ *   JSON keys change.
+ * - Safe to call on designs with no board objects: creates the board file with
+ *   an empty body and sets boardFileId.
+ *
+ * ## Trigger
+ *
+ * Called by DesignEditor on design open when designs.data.boardFileId is absent.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { seedFromText } from "@agent-native/core/collab";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  BOARD_FILENAME,
+  boardObjectEntryToHtmlFragment,
+  emptyBoardHtml,
+} from "../shared/board-file.js";
+import { parseBoardObjects } from "../shared/board-objects.js";
+
+export default defineAction({
+  description:
+    "Migrate the legacy boardObjects blob (designs.data.boardObjects) into the " +
+    "new board file architecture. Creates a __board__.html design file, writes " +
+    "each board object as an absolute-positioned HTML element (preserving " +
+    "negative coordinates), stores boardFileId in designs.data, and nulls " +
+    "boardObjects. Idempotent — returns immediately if boardFileId is already " +
+    "set. Requires editor access on the design.",
+  schema: z.object({
+    designId: z
+      .string()
+      .describe("Design project ID to migrate board objects for."),
+  }),
+  run: async ({ designId }) => {
+    await assertAccess("design", designId, "editor");
+
+    const db = getDb();
+
+    // ── 1. Idempotency guard ──────────────────────────────────────────────
+    // Read the design data JSON to check whether boardFileId is already set.
+    // guard:allow-unscoped — assertAccess "editor" above scopes this read to
+    // the requesting user's accessible designs.
+    const [existing] = await db
+      .select({ data: schema.designs.data })
+      .from(schema.designs)
+      .where(eq(schema.designs.id, designId))
+      .limit(1);
+
+    if (!existing) {
+      throw new Error(`Design "${designId}" not found.`);
+    }
+
+    let parsed: Record<string, unknown>;
+    try {
+      const raw = JSON.parse(existing.data);
+      parsed =
+        raw && typeof raw === "object" && !Array.isArray(raw)
+          ? (raw as Record<string, unknown>)
+          : {};
+    } catch {
+      parsed = {};
+    }
+
+    if (
+      typeof parsed["boardFileId"] === "string" &&
+      parsed["boardFileId"].length > 0
+    ) {
+      return {
+        designId,
+        migrated: false,
+        boardFileId: parsed["boardFileId"] as string,
+        reason: "boardFileId already set — migration already complete.",
+      };
+    }
+
+    // ── 2. Parse legacy board objects ────────────────────────────────────
+    const boardObjects = parseBoardObjects(parsed["boardObjects"]);
+    const entries = Object.values(boardObjects);
+
+    // ── 3. Build the board HTML ───────────────────────────────────────────
+    // Start from the canonical empty-board template and inject each entry as
+    // a direct <body> child.  Negative left/top are preserved — the migration
+    // intentionally does NOT clamp coords (appendCanvasPrimitiveToHtml clamps
+    // to x/y >= 0 for new screen primitives; the board surface has no such
+    // restriction).
+    let boardHtml = emptyBoardHtml();
+    if (entries.length > 0) {
+      const fragments = entries
+        .sort((a, b) => {
+          // Stable render order: lower z first, then creation order.
+          const az = a.geometry.z ?? 0;
+          const bz = b.geometry.z ?? 0;
+          if (az !== bz) return az - bz;
+          return a.createdAt < b.createdAt ? -1 : 1;
+        })
+        .map((entry) => boardObjectEntryToHtmlFragment(entry))
+        .join("\n");
+
+      // Insert fragments before </body>.
+      boardHtml = boardHtml.replace("</body>", `${fragments}\n</body>`);
+    }
+
+    const now = new Date().toISOString();
+
+    // ── 4. Upsert the board file and update designs.data atomically ───────
+    // Run in a transaction so concurrent opens cannot create two board files.
+    let boardFileId = "";
+
+    await db.transaction(async (tx) => {
+      // Re-read designs.data inside the transaction to guard against a
+      // concurrent migration that raced us.
+      const [fresh] = await tx
+        .select({ data: schema.designs.data })
+        .from(schema.designs)
+        .where(eq(schema.designs.id, designId))
+        .limit(1);
+
+      if (!fresh) {
+        throw new Error(`Design "${designId}" not found.`);
+      }
+
+      let freshParsed: Record<string, unknown>;
+      try {
+        const raw = JSON.parse(fresh.data);
+        freshParsed =
+          raw && typeof raw === "object" && !Array.isArray(raw)
+            ? (raw as Record<string, unknown>)
+            : {};
+      } catch {
+        freshParsed = {};
+      }
+
+      // Double-check inside the transaction.
+      if (
+        typeof freshParsed["boardFileId"] === "string" &&
+        freshParsed["boardFileId"].length > 0
+      ) {
+        boardFileId = freshParsed["boardFileId"] as string;
+        return; // Another concurrent call already finished — skip.
+      }
+
+      // Check if a __board__.html file was somehow already created (shouldn't
+      // happen in normal flow, but be defensive).
+      const [existingBoardFile] = await tx
+        .select({ id: schema.designFiles.id })
+        .from(schema.designFiles)
+        .where(
+          and(
+            eq(schema.designFiles.designId, designId),
+            eq(schema.designFiles.filename, BOARD_FILENAME),
+          ),
+        )
+        .limit(1);
+
+      if (existingBoardFile) {
+        // Board file exists but boardFileId was not set — link it and update
+        // its content.
+        boardFileId = existingBoardFile.id;
+        await tx
+          .update(schema.designFiles)
+          .set({ content: boardHtml, updatedAt: now })
+          .where(eq(schema.designFiles.id, boardFileId));
+      } else {
+        // Create the board file.
+        boardFileId = nanoid();
+        await tx.insert(schema.designFiles).values({
+          id: boardFileId,
+          designId,
+          filename: BOARD_FILENAME,
+          fileType: "html",
+          content: boardHtml,
+          createdAt: now,
+          updatedAt: now,
+        });
+      }
+
+      // Write boardFileId into designs.data; null out boardObjects.
+      const nextData: Record<string, unknown> = {
+        ...freshParsed,
+        boardFileId,
+        boardObjects: null,
+      };
+
+      await tx
+        .update(schema.designs)
+        .set({
+          data: JSON.stringify(nextData),
+          updatedAt: now,
+        })
+        .where(eq(schema.designs.id, designId));
+    });
+
+    // ── 5. Seed collab state for the new board file ───────────────────────
+    // (Best-effort: collab seeding after the file row is committed.)
+    try {
+      await seedFromText(boardFileId, boardHtml);
+    } catch {
+      // Non-fatal — the board file still renders from SQL content.
+    }
+
+    return {
+      designId,
+      migrated: true,
+      boardFileId,
+      migratedObjectCount: entries.length,
+      message:
+        entries.length > 0
+          ? `Migrated ${entries.length} board object(s) to board file ${boardFileId}.`
+          : `Created empty board file ${boardFileId} (no legacy board objects).`,
+    };
+  },
+});

package/corpus/templates/design/actions/navigate.ts

@@ -18,7 +18,8 @@
  *   --view       View name (list, editor, design-systems, present, templates, settings)
  *   --designId   Design ID (for editor/present views)
  *   --editorView Editor mode for designs: single or overview
- *   --inspectorTab Inspector tab for designs: design, tweaks, or extensions
+ *   --inspectorTab Inspector tab for designs: design or tweaks (extensions opens Tools for compatibility)
+ *   --leftPanel  Left editor panel: file, agent, assets, tools, or tokens
  *   --fileId     Screen/file id to focus in the design editor
  *   --filename   Screen filename to focus in the design editor
  *   --tool       Design editor tool to activate
@@ -47,9 +48,17 @@ const designEditorToolSchema = z.enum([
   "scale",
 ]);
 
+const designLeftPanelSchema = z.enum([
+  "file",
+  "agent",
+  "assets",
+  "tools",
+  "tokens",
+]);
+
 export default defineAction({
   description:
-    "Navigate the UI to a specific view or path. Views: list, editor, design-systems, present, templates, settings. Use --designId with editor/present views and --designSystemId with design-systems. For designs, use editorView=overview to show the infinite screens canvas, or editorView=single with fileId/filename/screen to focus a screen. Use inspectorTab=extensions to focus the in-editor extension panel. Use tool to activate a design editor tool.",
+    "Navigate the UI to a specific view or path. Views: list, editor, design-systems, present, templates, settings. Use --designId with editor/present views and --designSystemId with design-systems. For designs, use editorView=overview to show the infinite screens canvas, or editorView=single with fileId/filename/screen to focus a screen. Use leftPanel=file|agent|assets|tools|tokens to focus the Figma-style left rail. Legacy inspectorTab=extensions opens Tools. Use tool to activate a design editor tool.",
   schema: z
     .object({
       view: z
@@ -83,6 +92,10 @@ export default defineAction({
         .enum(["design", "tweaks", "extensions"])
         .optional()
         .describe("Alias for inspectorTab"),
+      leftPanel: designLeftPanelSchema
+        .optional()
+        .describe("Design editor left rail panel to focus"),
+      panel: designLeftPanelSchema.optional().describe("Alias for leftPanel"),
       fileId: z.string().optional().describe("Design file/screen ID to focus"),
       screenId: z.string().optional().describe("Alias for fileId"),
       filename: z
@@ -146,6 +159,8 @@ export default defineAction({
     if (editorView) nav.editorView = editorView;
     const inspectorTab = args.inspectorTab ?? args.inspector;
     if (inspectorTab) nav.inspectorTab = inspectorTab;
+    const leftPanel = args.leftPanel ?? args.panel;
+    if (leftPanel) nav.leftPanel = leftPanel;
     if (args.fileId) nav.fileId = args.fileId;
     if (args.screenId) nav.screenId = args.screenId;
     if (args.filename) nav.filename = args.filename;
@@ -159,7 +174,7 @@ export default defineAction({
       args.designId ? ` (design: ${args.designId})` : ""
     }${editorView ? ` (${editorView} view)` : ""}${
       inspectorTab ? ` (${inspectorTab} inspector)` : ""
-    }${
+    }${leftPanel ? ` (${leftPanel} panel)` : ""}${
       args.fileId || args.screenId || args.filename || args.screen
         ? ` (screen: ${args.fileId ?? args.screenId ?? args.filename ?? args.screen})`
         : ""

package/corpus/templates/design/actions/provider-api-catalog.ts

@@ -10,7 +10,7 @@ const ProviderSchema = z.enum(DESIGN_PROVIDER_API_IDS);
 
 export default defineAction({
   description:
-    "List raw HTTP API capabilities for Design-connected providers. Use before provider-api-request when design-token import convenience actions are too narrow. Returns provider base URLs, auth style, credential key names, docs/spec URLs, placeholders, and examples; never returns secret values.",
+    "List raw HTTP API capabilities for Design-connected providers such as GitHub and Figma. Use before provider-api-request when design-token, repository, or Figma-library convenience actions are too narrow. Returns provider base URLs, auth style, credential key names, docs/spec URLs, placeholders, and examples; never returns secret values.",
   schema: z.object({
     provider: ProviderSchema.optional().describe(
       "Optional provider id to inspect. Omit to list every Design provider API escape hatch.",
@@ -22,7 +22,7 @@ export default defineAction({
     return {
       providers: await listProviderApiCatalog(provider),
       guidance:
-        "Design actions like import-github are workflow shortcuts, not capability limits. When the GitHub API can answer the question with a better endpoint, query, body, pagination mode, metadata field, or API version, inspect docs/spec URLs and call provider-api-request directly. GitHub auth uses the saved GITHUB_TOKEN secret and never exposes the token value.",
+        "Design actions like import-github and list-figma-library-assets are workflow shortcuts, not capability limits. When GitHub or Figma can answer the question with a better endpoint, query, body, pagination mode, metadata field, or API version, inspect docs/spec URLs and call provider-api-request directly. Auth uses saved scoped secrets such as GITHUB_TOKEN or FIGMA_ACCESS_TOKEN and never exposes token values.",
     };
   },
 });

package/corpus/templates/design/actions/provider-api-docs.ts

@@ -25,7 +25,7 @@ const WebContentSearchSchema = z.object({
 
 export default defineAction({
   description:
-    "Inspect provider API docs/spec metadata, or fetch any public API documentation page, OpenAPI spec, changelog, or web page. Use this before provider-api-request when the exact GitHub endpoint, payload shape, pagination, or API version is uncertain.",
+    "Inspect provider API docs/spec metadata, or fetch any public API documentation page, OpenAPI spec, changelog, or web page. Use this before provider-api-request when the exact GitHub/Figma endpoint, payload shape, pagination, or API version is uncertain.",
   schema: z.object({
     provider: ProviderSchema.describe(
       "Provider whose API docs/spec to inspect.",

package/corpus/templates/design/actions/provider-api-request.ts

@@ -71,8 +71,8 @@ const PaginationSchema = z
 export default defineAction({
   description:
     "Make an arbitrary authenticated HTTP request to a Design-connected provider API. " +
-    "Use this as the flexible escape hatch when a convenience action cannot express the needed GitHub endpoint, file tree query, issue/search query, request body, pagination mode, payload shape, or API version. " +
-    "The request is constrained to the provider host, uses the saved GITHUB_TOKEN automatically, blocks private/internal URLs, and redacts secrets from responses. " +
+    "Use this as the flexible escape hatch when a convenience action cannot express the needed GitHub endpoint, Figma file/library endpoint, request body, pagination mode, payload shape, or API version. " +
+    "The request is constrained to the provider host, uses saved scoped credentials such as GITHUB_TOKEN or FIGMA_ACCESS_TOKEN automatically, blocks private/internal URLs, and redacts secrets from responses. " +
     "\n\nSTAGING MODE (preferred for large responses): Pass stageAs to write response items into a scratch dataset instead of returning the raw body. " +
     "Returns { dataset, rowCount, columns, sampleRows } so only a compact summary enters context. Use query-staged-dataset to aggregate, filter, and project the data without re-fetching. " +
     "\n\nPAGINATION: When stageAs is set, pass pagination config to fetch all pages server-side into the same dataset. For GitHub page pagination, use pageParam='page', pageSize from per_page, and itemsPath when the response object contains an items array.",
@@ -83,7 +83,7 @@ export default defineAction({
       .string()
       .min(1)
       .describe(
-        "Provider API path such as /repos/{owner}/{repo}/contents/{path}, /search/code, /issues, or a full URL on an allowed provider host. Use placeholders from provider-api-catalog when provided.",
+        "Provider API path such as /repos/{owner}/{repo}/contents/{path}, /search/code, /files/{fileKey}/components, /images/{fileKey}, or a full URL on an allowed provider host. Use placeholders from provider-api-catalog when provided.",
       ),
     query: z
       .unknown()

package/corpus/templates/design/actions/revoke-localhost-write-consent.ts

@@ -0,0 +1,48 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+
+export default defineAction({
+  description:
+    "Revoke a previously granted localhost write-consent for a design + connection. " +
+    "After revocation the agent can no longer write local files until the user re-grants consent. " +
+    "Requires editor access on the design.",
+  schema: z.object({
+    designId: z.string().describe("Design ID."),
+    connectionId: z
+      .string()
+      .describe("Localhost connection ID whose grant should be revoked."),
+  }),
+  run: async ({ designId, connectionId }) => {
+    await assertAccess("design", designId, "editor");
+
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+
+    const db = getDb();
+
+    const deleted = await db
+      .delete(schema.designLocalhostWriteGrants)
+      .where(
+        and(
+          eq(schema.designLocalhostWriteGrants.designId, designId),
+          eq(schema.designLocalhostWriteGrants.connectionId, connectionId),
+          eq(schema.designLocalhostWriteGrants.ownerEmail, ownerEmail),
+        ),
+      );
+
+    // `deleted` shape varies by dialect; check rows affected via the object.
+    const rowsAffected =
+      (deleted as unknown as { rowsAffected?: number })?.rowsAffected ?? 0;
+
+    return {
+      designId,
+      connectionId,
+      revoked: rowsAffected > 0,
+    };
+  },
+});