@agent-native/core 0.129.1 → 0.130.0

package/corpus/templates/design/actions/list-local-files.ts

@@ -6,22 +6,26 @@
  * grant (reads do not require user write consent, only editor access + a
  * valid bridge connection):
  *  1. assertAccess: the caller must have editor access to the design.
- *  2. Bridge URL resolution: only the current user's own connection row.
+ *  2. Bridge URL resolution: only the current user's own connection row, in
+ *     the caller's own org scope. A miss throws a classified 4xx from
+ *     server/lib/localhost-connection.ts so the client sees the actual
+ *     condition instead of a generic 500.
  *  3. Loopback check: bridgeUrl must resolve to localhost/127.0.0.1.
  *  4. Bridge token: the connection's stored bridge token is sent as
  *     X-Bridge-Token so the bridge can reject unauthorized callers.
  */
 
 import { defineAction } from "@agent-native/core";
-import {
-  getRequestOrgId,
-  getRequestUserEmail,
-} from "@agent-native/core/server/request-context";
 import { assertAccess } from "@agent-native/core/sharing";
-import { and, eq, isNull } from "drizzle-orm";
 import { z } from "zod";
 
-import { getDb, schema } from "../server/db/index.js";
+import {
+  fetchLocalhostBridge,
+  localhostBridgeRequestError,
+  requireLocalhostBridgeToken,
+  resolveLocalhostBridgeConnection,
+  resolveLocalhostConnectionScope,
+} from "../server/lib/localhost-connection.js";
 
 function isLoopbackHostname(hostname: string): boolean {
   const normalized = hostname.toLowerCase();
@@ -77,53 +81,25 @@ export default defineAction({
   run: async ({ designId, connectionId }) => {
     await assertAccess("design", designId, "editor");
 
-    const ownerEmail = getRequestUserEmail();
-    if (!ownerEmail) throw new Error("no authenticated user");
-    const orgId = getRequestOrgId() ?? null;
-
-    const db = getDb();
-    const [connection] = await db
-      .select({
-        bridgeUrl: schema.designLocalhostConnections.bridgeUrl,
-        bridgeToken: schema.designLocalhostConnections.bridgeToken,
-      })
-      .from(schema.designLocalhostConnections)
-      .where(
-        and(
-          eq(schema.designLocalhostConnections.id, connectionId),
-          eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
-          orgId
-            ? eq(schema.designLocalhostConnections.orgId, orgId)
-            : isNull(schema.designLocalhostConnections.orgId),
-        ),
-      )
-      .limit(1);
-
-    if (!connection?.bridgeUrl) {
-      throw new Error(
-        `No bridge URL found for connection "${connectionId}". ` +
-          "Ensure the design bridge is running (npx @agent-native/core@latest design connect).",
-      );
-    }
-    if (!connection.bridgeToken) {
-      throw new Error(
-        `No bridge token found for connection "${connectionId}". ` +
-          "Reconnect via npx @agent-native/core@latest design connect.",
-      );
-    }
+    const scope = await resolveLocalhostConnectionScope();
+    const connection = await resolveLocalhostBridgeConnection({
+      connectionId,
+      ...scope,
+    });
+    const bridgeToken = requireLocalhostBridgeToken(
+      connectionId,
+      connection.bridgeToken,
+    );
 
-    const bridgeUrl = normalizeBridgeUrl(connection.bridgeUrl);
-    const res = await fetch(`${bridgeUrl}/list-files`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-Bridge-Token": connection.bridgeToken,
-      },
-      body: JSON.stringify({}),
+    const res = await fetchLocalhostBridge({
+      bridgeUrl: normalizeBridgeUrl(connection.bridgeUrl),
+      operation: "list-files",
+      bridgeToken,
+      body: {},
     });
     if (!res.ok) {
       const errText = await res.text().catch(() => res.statusText);
-      throw new Error(`Bridge list-files failed (${res.status}): ${errText}`);
+      throw localhostBridgeRequestError("list-files", res.status, errText);
     }
     const body = (await res.json()) as {
       files?: Array<{ path: string; size: number }>;

package/corpus/templates/design/actions/list-localhost-connections.ts

@@ -1,12 +1,9 @@
 import { defineAction } from "@agent-native/core";
-import {
-  getRequestOrgId,
-  getRequestUserEmail,
-} from "@agent-native/core/server/request-context";
 import { and, desc, eq, isNull } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
+import { resolveLocalhostConnectionScope } from "../server/lib/localhost-connection.js";
 import type {
   DesignBridgeCapability,
   LocalhostDesignRouteManifest,
@@ -33,9 +30,7 @@ export default defineAction({
   readOnly: true,
   http: { method: "GET" },
   run: async ({ id, status }) => {
-    const ownerEmail = getRequestUserEmail();
-    if (!ownerEmail) throw new Error("no authenticated user");
-    const orgId = getRequestOrgId() ?? null;
+    const { ownerEmail, orgId } = await resolveLocalhostConnectionScope();
     const clauses = [
       eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
       orgId

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

@@ -31,6 +31,7 @@
 
 import { defineAction } from "@agent-native/core";
 import { seedFromText } from "@agent-native/core/collab";
+import { injectDocumentMarkup } from "@agent-native/core/shared";
 import { assertAccess } from "@agent-native/core/sharing";
 import { and, eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
@@ -181,8 +182,7 @@ export default defineAction({
         .map((entry) => boardObjectEntryToHtmlFragment(entry))
         .join("\n");
 
-      // Insert fragments before </body>.
-      boardHtml = boardHtml.replace("</body>", `${fragments}\n</body>`);
+      boardHtml = injectDocumentMarkup(boardHtml, `${fragments}\n`);
     }
 
     const now = new Date().toISOString();

package/corpus/templates/design/actions/open-visual-edit.ts

@@ -1,6 +1,19 @@
+import crypto from "node:crypto";
+import path from "node:path";
+
 import { defineAction, embedApp } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
-import { buildDeepLink } from "@agent-native/core/server";
+import {
+  buildDeepLink,
+  buildEmbedStartPath,
+  createEmbedSessionTicket,
+} from "@agent-native/core/server";
+import {
+  getRequestContext,
+  getRequestOrgId,
+  getRequestUserEmail,
+  runWithRequestContext,
+} from "@agent-native/core/server/request-context";
 import { eq } from "drizzle-orm";
 import { z } from "zod";
 
@@ -166,13 +179,53 @@ function isLoopbackUrl(value: string): boolean {
   );
 }
 
-function designOverviewDeepLink(designId: string): string {
+const LOCAL_VISUAL_EDIT_TICKET_TTL_SECONDS = 5 * 60;
+const LOCAL_VISUAL_EDIT_PRINCIPAL_DOMAIN =
+  "local.visual-edit.agent-native.invalid";
+
+/**
+ * Stable owner partition for Design rows created by the local CLI skill when
+ * no account session exists. This value is never installed as a browser
+ * session; it only lets one trusted in-process `pnpm action` invocation compose
+ * the existing owner-scoped actions before minting a narrow embed capability.
+ */
+export function localVisualEditWorkspacePrincipal(
+  workspacePath = process.cwd(),
+): string {
+  const workspaceId = crypto
+    .createHash("sha256")
+    .update(path.resolve(workspacePath))
+    .digest("hex")
+    .slice(0, 24);
+  return `workspace+${workspaceId}@${LOCAL_VISUAL_EDIT_PRINCIPAL_DOMAIN}`;
+}
+
+function localVisualEditPath(designId: string): string {
+  return `/visual-edit/${encodeURIComponent(designId)}?editorView=overview`;
+}
+
+function localVisualEditDeepLink(designId: string): string {
   return buildDeepLink({
     app: "design",
     view: "editor",
     params: { designId, editorView: "overview" },
-    to: `/design/${encodeURIComponent(designId)}?editorView=overview`,
+    to: localVisualEditPath(designId),
+  });
+}
+
+async function createCallerHandoff(
+  targetPath: string,
+  ownerEmail: string,
+  designId: string,
+): Promise<string> {
+  const ticket = await createEmbedSessionTicket({
+    ownerEmail,
+    orgId: getRequestOrgId(),
+    targetPath,
+    scope: `capability:visual-edit:design:${encodeURIComponent(designId)}`,
+    ttlSeconds: LOCAL_VISUAL_EDIT_TICKET_TTL_SECONDS,
   });
+  return buildEmbedStartPath(ticket.ticket);
 }
 
 function routeManifestFromScreens(args: {
@@ -211,7 +264,7 @@ function routeManifestFromScreens(args: {
 
 export default defineAction({
   description:
-    "Open or refresh a running localhost app in Design overview mode in one authenticated step. Registers the local bridge, creates or reuses a design, places URL-backed screens, stores the active visual-edit context, and navigates the current Design session to the canvas. Use this for /visual-edit launches and follow-up requests like adding a mobile-size screen.",
+    "Open or refresh a running localhost app in Design overview mode without requiring a Design account login. Registers the local bridge, creates or reuses a design, places URL-backed screens, stores the active visual-edit context, and navigates the current Design session to the canvas. Use this from the local /visual-edit skill and for follow-up requests like adding a mobile-size screen.",
   schema: z.object({
     designId: z
       .string()
@@ -310,153 +363,199 @@ export default defineAction({
       height: 680,
     }),
   },
-  run: async (args) => {
+  run: async (args, ctx) => {
     const devServerUrl = normalizeBaseUrl(args.devServerUrl);
-    const routeManifest = args.routeManifest
-      ? {
-          ...args.routeManifest,
-          devServerUrl: args.routeManifest.devServerUrl ?? devServerUrl,
-          rootPath: args.routeManifest.rootPath ?? args.rootPath,
+    const runForPrincipal = async () => {
+      const routeManifest = args.routeManifest
+        ? {
+            ...args.routeManifest,
+            devServerUrl: args.routeManifest.devServerUrl ?? devServerUrl,
+            rootPath: args.routeManifest.rootPath ?? args.rootPath,
+          }
+        : {
+            version: 1 as const,
+            sourceType: "localhost" as const,
+            devServerUrl,
+            rootPath: args.rootPath,
+            routes:
+              routeManifestFromScreens({
+                devServerUrl,
+                routes: args.routes,
+                paths: args.paths,
+              }) ?? [],
+            generatedAt: new Date().toISOString(),
+          };
+      const connection = await connectLocalhostAction.run({
+        // Let connect-localhost be the single source of truth for stable
+        // per-user/per-org id derivation. Duplicating it here can create a second
+        // tokenless row after the CLI self-registers the bridge token.
+        id: args.connectionId,
+        name: args.name,
+        devServerUrl,
+        bridgeUrl: args.bridgeUrl,
+        rootPath: routeManifest.rootPath ?? args.rootPath,
+        routeManifest,
+        capabilities: args.capabilities,
+        bridgeToken: args.bridgeToken,
+        previewToken: args.previewToken,
+        status: "connected",
+      });
+
+      let designId = args.designId;
+      let createdDesign = false;
+      let publicReadOnly = false;
+      if (!designId) {
+        const design = await createDesignAction.run({
+          title: args.title ?? `${new URL(devServerUrl).host} visual edit`,
+          description:
+            args.description ??
+            "URL-backed localhost screens prepared by visual-edit.",
+          projectType: "prototype",
+        });
+        designId = design.id;
+        createdDesign = true;
+        if (args.publicReadOnly && isLoopbackUrl(devServerUrl)) {
+          publicReadOnly = true;
+          await getDb()
+            .update(schema.designs)
+            .set({ visibility: "public" })
+            .where(eq(schema.designs.id, designId));
         }
-      : {
-          version: 1 as const,
-          sourceType: "localhost" as const,
-          devServerUrl,
-          rootPath: args.rootPath,
-          routes:
-            routeManifestFromScreens({
-              devServerUrl,
-              routes: args.routes,
-              paths: args.paths,
-            }) ?? [],
-          generatedAt: new Date().toISOString(),
-        };
-    const connection = await connectLocalhostAction.run({
-      // Let connect-localhost be the single source of truth for stable
-      // per-user/per-org id derivation. Duplicating it here can create a second
-      // tokenless row after the CLI self-registers the bridge token.
-      id: args.connectionId,
-      name: args.name,
-      devServerUrl,
-      bridgeUrl: args.bridgeUrl,
-      rootPath: routeManifest.rootPath ?? args.rootPath,
-      routeManifest,
-      capabilities: args.capabilities,
-      bridgeToken: args.bridgeToken,
-      previewToken: args.previewToken,
-      status: "connected",
-    });
+      }
 
-    let designId = args.designId;
-    let createdDesign = false;
-    let publicReadOnly = false;
-    if (!designId) {
-      const design = await createDesignAction.run({
-        title: args.title ?? `${new URL(devServerUrl).host} visual edit`,
-        description:
-          args.description ??
-          "URL-backed localhost screens prepared by visual-edit.",
-        projectType: "prototype",
-      });
-      designId = design.id;
-      createdDesign = true;
-      if (args.publicReadOnly && isLoopbackUrl(devServerUrl)) {
-        publicReadOnly = true;
-        await getDb()
-          .update(schema.designs)
-          .set({ visibility: "public" })
-          .where(eq(schema.designs.id, designId));
+      const viewports = resolveViewports(args.viewports);
+      const requestedRoutes = args.routes?.length
+        ? args.routes
+        : args.paths?.length
+          ? args.paths.map((path) => ({ path }))
+          : viewports
+            ? routeManifest.routes.map((route) => ({
+                routeId: route.id,
+                path: route.path,
+                title: route.title,
+              }))
+            : undefined;
+      if (viewports && !requestedRoutes?.length) {
+        throw new Error(
+          "viewports needs at least one route: pass routes/paths, or connect a bridge whose manifest lists routes.",
+        );
       }
-    }
 
-    const viewports = resolveViewports(args.viewports);
-    const requestedRoutes = args.routes?.length
-      ? args.routes
-      : args.paths?.length
-        ? args.paths.map((path) => ({ path }))
-        : viewports
-          ? routeManifest.routes.map((route) => ({
-              routeId: route.id,
-              path: route.path,
-              title: route.title,
-            }))
-          : undefined;
-    if (viewports && !requestedRoutes?.length) {
-      throw new Error(
-        "viewports needs at least one route: pass routes/paths, or connect a bridge whose manifest lists routes.",
-      );
-    }
+      const screens = await addLocalhostScreensAction.run({
+        designId,
+        connectionId: connection.id,
+        routes:
+          viewports && requestedRoutes
+            ? expandRoutesAcrossViewports({
+                routes: requestedRoutes,
+                viewports,
+                startX: args.startX ?? 0,
+                startY: args.startY ?? 0,
+                gap: args.gap ?? 160,
+              })
+            : args.routes,
+        paths: viewports ? undefined : args.paths,
+        defaultWidth: args.defaultWidth,
+        defaultHeight: args.defaultHeight,
+        startX: args.startX,
+        startY: args.startY,
+        gap: args.gap,
+      });
 
-    const screens = await addLocalhostScreensAction.run({
-      designId,
-      connectionId: connection.id,
-      routes:
-        viewports && requestedRoutes
-          ? expandRoutesAcrossViewports({
-              routes: requestedRoutes,
-              viewports,
-              startX: args.startX ?? 0,
-              startY: args.startY ?? 0,
-              gap: args.gap ?? 160,
-            })
-          : args.routes,
-      paths: viewports ? undefined : args.paths,
-      defaultWidth: args.defaultWidth,
-      defaultHeight: args.defaultHeight,
-      startX: args.startX,
-      startY: args.startY,
-      gap: args.gap,
-    });
+      const urlPath = localVisualEditPath(designId);
+      await writeAppState("visual-edit", {
+        designId,
+        connectionId: connection.id,
+        devServerUrl,
+        bridgeUrl: connection.bridgeUrl,
+        rootPath: connection.rootPath,
+        urlPath,
+        screens: screens.screens,
+        updatedAt: new Date().toISOString(),
+      });
 
-    const urlPath = `/design/${encodeURIComponent(
-      designId,
-    )}?editorView=overview`;
-    await writeAppState("visual-edit", {
-      designId,
-      connectionId: connection.id,
-      devServerUrl,
-      bridgeUrl: connection.bridgeUrl,
-      rootPath: connection.rootPath,
-      urlPath,
-      screens: screens.screens,
-      updatedAt: new Date().toISOString(),
-    });
+      if (args.navigate) {
+        await navigateAction.run({
+          view: "editor",
+          designId,
+          editorView: "overview",
+          path: urlPath,
+        });
+      }
 
-    if (args.navigate) {
-      await navigateAction.run({
-        view: "editor",
+      const ownerEmail = getRequestUserEmail();
+      if (!ownerEmail) {
+        throw new Error("visual-edit principal was not established");
+      }
+      const deepLink = localVisualEditDeepLink(designId);
+      const embedStartUrl = isLoopbackUrl(devServerUrl)
+        ? await createCallerHandoff(urlPath, ownerEmail, designId)
+        : undefined;
+
+      const result = {
         designId,
-        editorView: "overview",
-        path: urlPath,
-      });
+        connectionId: connection.id,
+        createdDesign,
+        publicReadOnly,
+        devServerUrl,
+        bridgeUrl: connection.bridgeUrl,
+        rootPath: connection.rootPath,
+        screenCount: screens.screenCount,
+        screens: screens.screens,
+        placedFrames: screens.placedFrames,
+        overview: true,
+        urlPath,
+        // Safe for model-visible action text and retained links. The MCP App
+        // receives the one-time launcher separately through hidden metadata.
+        openUrl: deepLink,
+        // Minted/stored by connect-localhost; the skill starts the bridge with
+        // `design connect --bridge-token <this>` so bridge and row agree.
+        bridgeToken: connection.bridgeToken,
+        previewToken: connection.previewToken,
+      };
+      if (embedStartUrl) {
+        // Trusted hosts and the CLI runner read this property directly. Keeping
+        // it non-enumerable prevents generic object/string serialization from
+        // copying the single-use bearer into model-visible action output.
+        Object.defineProperty(result, "embedStartUrl", {
+          value: embedStartUrl,
+          enumerable: false,
+        });
+      }
+      return result as typeof result & { embedStartUrl?: string };
+    };
+
+    if (getRequestUserEmail()) return runForPrincipal();
+    if (ctx?.caller !== "cli" || !isLoopbackUrl(devServerUrl)) {
+      throw new Error(
+        "Signed-out visual-edit is available only through the local CLI for a loopback app.",
+      );
+    }
+    if (args.publicReadOnly === false) {
+      throw new Error(
+        "Signed-out local visual-edit requires publicReadOnly so the resource can be opened through its narrow editor capability. Sign in to create a private Design resource.",
+      );
     }
 
-    return {
-      designId,
-      connectionId: connection.id,
-      createdDesign,
-      publicReadOnly,
-      devServerUrl,
-      bridgeUrl: connection.bridgeUrl,
-      rootPath: connection.rootPath,
-      screenCount: screens.screenCount,
-      screens: screens.screens,
-      placedFrames: screens.placedFrames,
-      overview: true,
-      urlPath,
-      openUrl: designOverviewDeepLink(designId),
-      // Minted/stored by connect-localhost; the skill starts the bridge with
-      // `design connect --bridge-token <this>` so bridge and row agree.
-      bridgeToken: connection.bridgeToken,
-      previewToken: connection.previewToken,
-    };
+    return runWithRequestContext(
+      {
+        ...(getRequestContext() ?? {}),
+        userEmail: localVisualEditWorkspacePrincipal(),
+        orgId: undefined,
+      },
+      runForPrincipal,
+    );
   },
   link: ({ result }) => {
     if (!result || typeof result !== "object") return null;
-    const designId = (result as { designId?: string }).designId;
+    const { designId } = result as {
+      designId?: string;
+    };
     if (!designId) return null;
     return {
-      url: designOverviewDeepLink(designId),
+      // The single-use embed ticket stays in MCP result metadata. Keep the
+      // model-visible link credential-free.
+      url: localVisualEditDeepLink(designId),
       label: "Open overview",
       view: "editor",
     };

package/corpus/templates/design/actions/read-local-file.ts

@@ -6,7 +6,10 @@
  * grant (reads do not require user write consent, only editor access + a
  * valid bridge connection):
  *  1. assertAccess: the caller must have editor access to the design.
- *  2. Bridge URL resolution: only the current user's own connection row.
+ *  2. Bridge URL resolution: only the current user's own connection row, in
+ *     the caller's own org scope. A miss throws a classified 4xx from
+ *     server/lib/localhost-connection.ts so the client sees the actual
+ *     condition instead of a generic 500.
  *  3. Loopback check: bridgeUrl must resolve to localhost/127.0.0.1.
  *  4. Bridge token: the connection's stored bridge token is sent as
  *     X-Bridge-Token so the bridge can reject unauthorized callers. The
@@ -15,15 +18,16 @@
  */
 
 import { defineAction } from "@agent-native/core";
-import {
-  getRequestOrgId,
-  getRequestUserEmail,
-} from "@agent-native/core/server/request-context";
 import { assertAccess } from "@agent-native/core/sharing";
-import { and, eq, isNull } from "drizzle-orm";
 import { z } from "zod";
 
-import { getDb, schema } from "../server/db/index.js";
+import {
+  fetchLocalhostBridge,
+  localhostBridgeRequestError,
+  requireLocalhostBridgeToken,
+  resolveLocalhostBridgeConnection,
+  resolveLocalhostConnectionScope,
+} from "../server/lib/localhost-connection.js";
 
 function isLoopbackHostname(hostname: string): boolean {
   const normalized = hostname.toLowerCase();
@@ -81,53 +85,25 @@ export default defineAction({
   run: async ({ designId, connectionId, path: relPath }) => {
     await assertAccess("design", designId, "editor");
 
-    const ownerEmail = getRequestUserEmail();
-    if (!ownerEmail) throw new Error("no authenticated user");
-    const orgId = getRequestOrgId() ?? null;
-
-    const db = getDb();
-    const [connection] = await db
-      .select({
-        bridgeUrl: schema.designLocalhostConnections.bridgeUrl,
-        bridgeToken: schema.designLocalhostConnections.bridgeToken,
-      })
-      .from(schema.designLocalhostConnections)
-      .where(
-        and(
-          eq(schema.designLocalhostConnections.id, connectionId),
-          eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
-          orgId
-            ? eq(schema.designLocalhostConnections.orgId, orgId)
-            : isNull(schema.designLocalhostConnections.orgId),
-        ),
-      )
-      .limit(1);
-
-    if (!connection?.bridgeUrl) {
-      throw new Error(
-        `No bridge URL found for connection "${connectionId}". ` +
-          "Ensure the design bridge is running (npx @agent-native/core@latest design connect).",
-      );
-    }
-    if (!connection.bridgeToken) {
-      throw new Error(
-        `No bridge token found for connection "${connectionId}". ` +
-          "Reconnect via npx @agent-native/core@latest design connect.",
-      );
-    }
+    const scope = await resolveLocalhostConnectionScope();
+    const connection = await resolveLocalhostBridgeConnection({
+      connectionId,
+      ...scope,
+    });
+    const bridgeToken = requireLocalhostBridgeToken(
+      connectionId,
+      connection.bridgeToken,
+    );
 
-    const bridgeUrl = normalizeBridgeUrl(connection.bridgeUrl);
-    const res = await fetch(`${bridgeUrl}/read-file`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-Bridge-Token": connection.bridgeToken,
-      },
-      body: JSON.stringify({ relPath }),
+    const res = await fetchLocalhostBridge({
+      bridgeUrl: normalizeBridgeUrl(connection.bridgeUrl),
+      operation: "read-file",
+      bridgeToken,
+      body: { relPath },
     });
     if (!res.ok) {
       const errText = await res.text().catch(() => res.statusText);
-      throw new Error(`Bridge read-file failed (${res.status}): ${errText}`);
+      throw localhostBridgeRequestError("read-file", res.status, errText);
     }
     const body = (await res.json()) as {
       content?: string;