@agent-native/core 0.84.56 → 0.84.58

package/corpus/templates/clips/app/i18n/zh-CN.ts

@@ -403,7 +403,7 @@ const messages = {
     agentPrompt:
       "获取这个 Clips 代理上下文 URL：{{agentContextUrl}}。使用 transcript.segments 读取语音上下文，获取 recommendedFrames 或帧 API URL 来查看屏幕，并在 browserDiagnostics 存在时检查经过脱敏的控制台日志和 fetch/XHR 请求元数据。",
     agentTokenDescription:
-      "该代理 URL 使用短期令牌，因此代理可以在不暴露密码的情况下读取剪辑。",
+      "这个临时代理 URL 可让代理读取剪辑，而无需将其设为公开。它会在两小时后过期。",
     gifPreview: "GIF 预览",
     openPlayer: "开放玩家",
     downloadMp4: "下载MP4",

package/corpus/templates/clips/app/i18n/zh-TW.ts

@@ -403,7 +403,7 @@ const messages = {
     agentPrompt:
       "取得這個 Clips Agent 脈絡 URL：{{agentContextUrl}}。使用 transcript.segments 讀取語音脈絡，取得 recommendedFrames 或影格 API URL 來查看螢幕，並在 browserDiagnostics 存在時檢查已遮蔽的主控台記錄和 fetch/XHR 請求中繼資料。",
     agentTokenDescription:
-      "此 Agent URL 使用短期權杖，因此 Agent 可以在不暴露密碼的情況下讀取剪輯。",
+      "這個臨時 Agent URL 可讓 Agent 讀取剪輯，而不必將其設為公開。它會在兩小時後過期。",
     gifPreview: "GIF 預覽",
     openPlayer: "開啟播放器",
     downloadMp4: "下載 MP4",

package/corpus/templates/clips/app/routes/share.$shareId.tsx

@@ -11,6 +11,7 @@ import {
 import {
   getRequestUserEmail,
   signShortLivedToken,
+  verifyShortLivedToken,
 } from "@agent-native/core/server";
 import { resolveAccess } from "@agent-native/core/sharing";
 import {
@@ -32,7 +33,12 @@ import {
   useState,
   type ReactNode,
 } from "react";
-import type { LoaderFunctionArgs, MetaFunction } from "react-router";
+import {
+  data,
+  type HeadersArgs,
+  type LoaderFunctionArgs,
+  type MetaFunction,
+} from "react-router";
 import { useLoaderData, useNavigate, useParams } from "react-router";
 
 import { CaptureInstallButton } from "@/components/capture-install-options";
@@ -65,7 +71,12 @@ import { parsePlaybackSpeed } from "@/lib/playback-speed";
 import { isStorageSetupFailureReason } from "@/lib/storage-failures";
 
 import { getDb, schema } from "../../server/db";
-import { buildAgentApiUrls, safeJsonForHtml } from "../../shared/agent-context";
+import { CLIPS_AGENT_ACCESS_PARAM } from "../../server/lib/public-agent-context";
+import {
+  agentAccessTokenResourceId,
+  buildAgentApiUrls,
+  safeJsonForHtml,
+} from "../../shared/agent-context";
 import {
   isLoomEmbedBackedRecording,
   isLoomRecordingSource,
@@ -99,6 +110,34 @@ type SharePageLoaderData = {
   shareUrl: string | null;
 };
 
+const PRIVATE_AGENT_SHARE_HEADERS = {
+  "Cache-Control": "private, max-age=0, no-store",
+  "Referrer-Policy": "no-referrer",
+};
+
+function emptyLoaderData(url: URL): SharePageLoaderData {
+  return {
+    recording: null,
+    agentContextUrl: null,
+    origin: url.origin,
+    shareUrl: null,
+  };
+}
+
+function shareLoaderData(
+  payload: SharePageLoaderData,
+  privateAgentAccess = false,
+) {
+  if (!privateAgentAccess) return payload;
+  return data(payload, {
+    headers: PRIVATE_AGENT_SHARE_HEADERS,
+  });
+}
+
+export function headers({ loaderHeaders }: HeadersArgs) {
+  return loaderHeaders;
+}
+
 function failureDetail(reason: string | null | undefined): string | null {
   const trimmed = reason?.trim();
   if (!trimmed) return null;
@@ -132,13 +171,7 @@ function shouldShowGeneratedTitleSkeleton(
 
 export async function loader({ params, url }: LoaderFunctionArgs) {
   const id = params.shareId;
-  if (!id)
-    return {
-      recording: null,
-      agentContextUrl: null,
-      origin: url.origin,
-      shareUrl: null,
-    };
+  if (!id) return emptyLoaderData(url);
 
   const [rec] = await getDb()
     .select({
@@ -151,6 +184,7 @@ export async function loader({ params, url }: LoaderFunctionArgs) {
       status: schema.recordings.status,
       ownerEmail: schema.recordings.ownerEmail,
       password: schema.recordings.password,
+      expiresAt: schema.recordings.expiresAt,
       archivedAt: schema.recordings.archivedAt,
       trashedAt: schema.recordings.trashedAt,
     })
@@ -158,24 +192,25 @@ export async function loader({ params, url }: LoaderFunctionArgs) {
     .where(eq(schema.recordings.id, id))
     .limit(1);
 
-  if (!rec)
-    return {
-      recording: null,
-      agentContextUrl: null,
-      origin: url.origin,
-      shareUrl: null,
-    };
+  const agentAccessToken = url.searchParams.get(CLIPS_AGENT_ACCESS_PARAM) ?? "";
+  const hasAgentAccessToken = Boolean(agentAccessToken);
+  const tokenGrantsAgentAccess = agentAccessToken
+    ? verifyShortLivedToken(agentAccessToken, agentAccessTokenResourceId(id)).ok
+    : false;
+
+  if (!rec) return shareLoaderData(emptyLoaderData(url), hasAgentAccessToken);
+
+  if (rec.expiresAt) {
+    const expires = new Date(rec.expiresAt).getTime();
+    if (Number.isFinite(expires) && expires < Date.now()) {
+      return shareLoaderData(emptyLoaderData(url), hasAgentAccessToken);
+    }
+  }
 
-  if (rec.visibility !== "public") {
+  if (rec.visibility !== "public" && !tokenGrantsAgentAccess) {
     const userEmail = getRequestUserEmail();
     const access = userEmail ? await resolveAccess("recording", id) : null;
-    if (!access)
-      return {
-        recording: null,
-        agentContextUrl: null,
-        origin: url.origin,
-        shareUrl: null,
-      };
+    if (!access) return emptyLoaderData(url);
   }
 
   const recording: SharePageMetaRecording = {
@@ -190,29 +225,37 @@ export async function loader({ params, url }: LoaderFunctionArgs) {
     trashedAt: rec.trashedAt,
   };
   const canExposeAgentContext =
-    rec.visibility === "public" && !rec.archivedAt && !rec.trashedAt;
-  const token =
-    canExposeAgentContext &&
-    rec.password &&
-    getRequestUserEmail() === rec.ownerEmail
-      ? signShortLivedToken({ resourceId: id })
+    (rec.visibility === "public" || tokenGrantsAgentAccess) &&
+    !rec.archivedAt &&
+    !rec.trashedAt;
+  const token = tokenGrantsAgentAccess
+    ? agentAccessToken
+    : canExposeAgentContext &&
+        rec.password &&
+        getRequestUserEmail() === rec.ownerEmail
+      ? signShortLivedToken({ resourceId: agentAccessTokenResourceId(id) })
       : undefined;
   const canExposeAnonymousAgentContext = canExposeAgentContext && !rec.password;
   const canExposeOwnerAgentContext = canExposeAgentContext && Boolean(token);
-  return {
-    recording,
-    origin: url.origin,
-    shareUrl: `${url.origin}${url.pathname}`,
-    agentContextUrl:
-      canExposeAnonymousAgentContext || canExposeOwnerAgentContext
-        ? buildAgentApiUrls(id, {
-            origin: url.origin,
-            basePath:
-              process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH || "",
-            token,
-          }).contextUrl
-        : null,
-  };
+  return shareLoaderData(
+    {
+      recording,
+      origin: url.origin,
+      shareUrl: `${url.origin}${url.pathname}`,
+      agentContextUrl:
+        canExposeAnonymousAgentContext || canExposeOwnerAgentContext
+          ? buildAgentApiUrls(id, {
+              origin: url.origin,
+              basePath:
+                process.env.VITE_APP_BASE_PATH ||
+                process.env.APP_BASE_PATH ||
+                "",
+              token,
+            }).contextUrl
+          : null,
+    },
+    hasAgentAccessToken || canExposeOwnerAgentContext,
+  );
 }
 
 export const meta: MetaFunction<typeof loader> = ({ loaderData }) => {
@@ -273,7 +316,7 @@ function AgentDiscovery({
         {t("sharePage.agentReadableContext")}
       </a>
       <script
-        type="application/json"
+        type="application/agent-native+json"
         id="clips-agent-context"
         dangerouslySetInnerHTML={{ __html: safeJsonForHtml(payload) }}
       />
@@ -362,9 +405,17 @@ export default function ShareRoute() {
     [],
   );
   const [downloading, setDownloading] = useState(false);
+  const agentAccessToken = useMemo(() => {
+    if (typeof window === "undefined") return "";
+    return (
+      new URLSearchParams(window.location.search).get(
+        CLIPS_AGENT_ACCESS_PARAM,
+      ) ?? ""
+    );
+  }, []);
 
   const dataQ = useQuery({
-    queryKey: ["public-recording", shareId, password],
+    queryKey: ["public-recording", shareId, password, agentAccessToken],
     queryFn: async () => {
       const url = new URL(
         `${appBasePath()}/api/public-recording`,
@@ -372,6 +423,9 @@ export default function ShareRoute() {
       );
       url.searchParams.set("id", shareId ?? "");
       if (password) url.searchParams.set("password", password);
+      if (agentAccessToken) {
+        url.searchParams.set(CLIPS_AGENT_ACCESS_PARAM, agentAccessToken);
+      }
       const res = await fetch(url.toString());
       const data = await res.json().catch(() => ({}));
       return { ok: res.ok, status: res.status, data };

package/corpus/templates/clips/changelog/2026-07-02-private-recordings-can-be-shared-with-agents-through-temporary-links-without-making-them-public.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-02
+---
+
+Private recordings can be shared with agents through temporary links without making them public.

package/corpus/templates/clips/server/lib/public-agent-context.ts

@@ -9,6 +9,7 @@ import { asc, eq } from "drizzle-orm";
 import { getRequestURL, setResponseHeader, type H3Event } from "h3";
 
 import {
+  agentAccessTokenResourceId,
   buildAgentApiUrls,
   buildRecommendedFrames,
   CLIP_AGENT_CONTEXT_VERSION,
@@ -53,6 +54,8 @@ export type PublicAgentAccessResult =
   | { ok: false; failure: PublicAgentFailure };
 
 const DEFAULT_MAX_AGENT_FRAME_MEDIA_BYTES = 200 * 1024 * 1024;
+export const CLIPS_AGENT_ACCESS_PARAM = "agent_access";
+export const CLIPS_AGENT_ACCESS_TTL_SECONDS = 2 * 60 * 60;
 
 function sameOwnerEmail(
   a: string | null | undefined,
@@ -207,8 +210,20 @@ export async function loadPublicAgentAccess(
   const viewerIsOwner = Boolean(
     session?.email && sameOwnerEmail(session.email, recording.ownerEmail),
   );
+  const suppliedToken = options.token ?? "";
+  const tokenAccess = suppliedToken
+    ? verifyShortLivedToken(
+        suppliedToken,
+        agentAccessTokenResourceId(recording.id),
+      )
+    : null;
+  const tokenAllowsAgentAccess = Boolean(tokenAccess?.ok);
 
-  if (recording.visibility !== "public" && !viewerIsOwner) {
+  if (
+    recording.visibility !== "public" &&
+    !viewerIsOwner &&
+    !tokenAllowsAgentAccess
+  ) {
     return {
       ok: false,
       failure: { status: 404, body: { error: "Not found" } },
@@ -229,26 +244,22 @@ export async function loadPublicAgentAccess(
   }
 
   let apiToken: string | null = null;
+  if (tokenAllowsAgentAccess) {
+    apiToken = suppliedToken;
+  }
   if (
     recording.password &&
     recording.visibility === "public" &&
     viewerIsOwner
   ) {
-    apiToken = signShortLivedToken({ resourceId: recording.id });
+    apiToken = signShortLivedToken({
+      resourceId: agentAccessTokenResourceId(recording.id),
+    });
   }
 
   if (recording.password && !viewerIsOwner) {
-    const suppliedToken = options.token ?? "";
     const suppliedPassword = options.password ?? "";
-    let allowed = false;
-
-    if (suppliedToken) {
-      const result = verifyShortLivedToken(suppliedToken, recording.id);
-      if (result.ok) {
-        allowed = true;
-        apiToken = suppliedToken;
-      }
-    }
+    let allowed = tokenAllowsAgentAccess;
 
     if (
       !allowed &&
@@ -256,7 +267,9 @@ export async function loadPublicAgentAccess(
       verifySharePassword(suppliedPassword, recording.password)
     ) {
       allowed = true;
-      apiToken = signShortLivedToken({ resourceId: recording.id });
+      apiToken = signShortLivedToken({
+        resourceId: agentAccessTokenResourceId(recording.id),
+      });
     }
 
     if (!allowed) {

package/corpus/templates/clips/server/routes/api/agent-context.json.get.ts

@@ -23,6 +23,7 @@ import {
   loadPublicAgentAccess,
   parseAgentChapters,
   queryString,
+  CLIPS_AGENT_ACCESS_PARAM,
 } from "../../lib/public-agent-context.js";
 
 export default defineEventHandler(async (event: H3Event) => {
@@ -32,7 +33,7 @@ export default defineEventHandler(async (event: H3Event) => {
   const id = queryString(query.id);
   const accessResult = await loadPublicAgentAccess(event, id, {
     password: queryString(query.password),
-    token: queryString(query.t),
+    token: queryString(query[CLIPS_AGENT_ACCESS_PARAM]) || queryString(query.t),
   });
 
   if (!accessResult.ok) {

package/corpus/templates/clips/server/routes/api/agent-frame.jpg.get.ts

@@ -13,6 +13,7 @@ import {
 } from "h3";
 
 import {
+  CLIPS_AGENT_ACCESS_PARAM,
   loadPublicAgentAccess,
   loadRecordingMediaBytes,
   queryString,
@@ -95,7 +96,7 @@ export default defineEventHandler(async (event: H3Event) => {
   const id = queryString(query.id);
   const accessResult = await loadPublicAgentAccess(event, id, {
     password: queryString(query.password),
-    token: queryString(query.t),
+    token: queryString(query[CLIPS_AGENT_ACCESS_PARAM]) || queryString(query.t),
   });
 
   if (!accessResult.ok) {

package/corpus/templates/clips/server/routes/api/agent-transcript.json.get.ts

@@ -16,6 +16,7 @@ import { buildAgentApiUrls } from "../../../shared/agent-context.js";
 import { isLoomEmbedBackedRecording } from "../../../shared/loom.js";
 import {
   applyAgentJsonHeaders,
+  CLIPS_AGENT_ACCESS_PARAM,
   getServerAppBasePath,
   loadAgentTranscript,
   loadPublicAgentAccess,
@@ -30,7 +31,7 @@ export default defineEventHandler(async (event: H3Event) => {
   const id = queryString(query.id);
   const accessResult = await loadPublicAgentAccess(event, id, {
     password: queryString(query.password),
-    token: queryString(query.t),
+    token: queryString(query[CLIPS_AGENT_ACCESS_PARAM]) || queryString(query.t),
   });
 
   if (!accessResult.ok) {

package/corpus/templates/clips/server/routes/api/public-recording.get.ts

@@ -26,7 +26,10 @@ import {
   type H3Event,
 } from "h3";
 
-import { buildAgentApiUrls } from "../../../shared/agent-context.js";
+import {
+  agentAccessTokenResourceId,
+  buildAgentApiUrls,
+} from "../../../shared/agent-context.js";
 import {
   normalizeTranscriptSegments,
   parseTranscriptSegments,
@@ -248,7 +251,9 @@ export default defineEventHandler(async (event) => {
     rec.visibility === "public" && !rec.archivedAt && !rec.trashedAt;
   const agentToken =
     canExposeAgentContext && rec.password
-      ? signShortLivedToken({ resourceId: recordingId })
+      ? signShortLivedToken({
+          resourceId: agentAccessTokenResourceId(recordingId),
+        })
       : undefined;
   const agentContextUrl = canExposeAgentContext
     ? buildAgentApiUrls(recordingId, {

package/corpus/templates/clips/shared/agent-context.ts

@@ -4,6 +4,11 @@ export const CLIP_AGENT_CONTEXT_VERSION = 1;
 export const AGENT_CONTEXT_ENDPOINT = "/api/agent-context.json";
 export const AGENT_TRANSCRIPT_ENDPOINT = "/api/agent-transcript.json";
 export const AGENT_FRAME_ENDPOINT = "/api/agent-frame.jpg";
+export const CLIP_AGENT_ACCESS_TOKEN_PREFIX = "clip-agent-context";
+
+export function agentAccessTokenResourceId(recordingId: string): string {
+  return `${CLIP_AGENT_ACCESS_TOKEN_PREFIX}:${recordingId}`;
+}
 
 export interface AgentApiUrls {
   contextUrl: string;

package/corpus/templates/design/actions/list-design-extensions.ts

@@ -68,7 +68,7 @@ const FIRST_PARTY_EXTENSIONS: FirstPartyDesignExtension[] = [
     id: "design.asset-library",
     name: "Asset Library",
     description:
-      "Browse and insert Design-native primitives, generated or uploaded media, and rendered Figma library components into the active design screen. " +
+      "Browse and insert Design primitives, generated or uploaded media, and rendered Figma library components into the active design screen. " +
       "Selection-aware: inserts near the selected element when one is active.",
     icon: "Photo",
     availability: "available",
@@ -77,7 +77,7 @@ const FIRST_PARTY_EXTENSIONS: FirstPartyDesignExtension[] = [
     capabilities: [
       {
         id: "native",
-        label: "Browse Design-native assets",
+        label: "Browse Design assets",
         status: "available",
         reason:
           "Uses list-design-native-assets and insert-design-native-asset for editable HTML primitives/components.",

package/corpus/templates/design/app/components/design/CodeWorkbenchHost.tsx

@@ -28,10 +28,11 @@ import { Button } from "@/components/ui/button";
 import { Spinner } from "@/components/ui/spinner";
 import { cn } from "@/lib/utils";
 
-interface CodeWorkbenchTheme {
-  colorScheme: "light" | "dark";
-  values: Record<string, string>;
-}
+import {
+  normalizeMonacoThemeColor,
+  readCodeWorkbenchTheme,
+  type CodeWorkbenchTheme,
+} from "./code-workbench-theme";
 
 interface CodeWorkbenchDraft {
   content: string;
@@ -56,87 +57,6 @@ interface CodeWorkbenchHostProps {
   onActiveFileChange?: (file: CodeWorkbenchActiveFile | null) => void;
 }
 
-const WORKBENCH_THEME_VARS: Record<string, string[]> = {
-  "--workbench-bg": ["--design-editor-panel-bg", "--background"],
-  "--workbench-sidebar-bg": ["--design-editor-panel-bg", "--card"],
-  "--workbench-editor-bg": ["--design-editor-panel-bg", "--background"],
-  "--workbench-surface-bg": ["--design-editor-control-bg", "--muted"],
-  "--workbench-border": ["--design-editor-control-border", "--border"],
-  "--workbench-fg": ["--foreground"],
-  "--workbench-muted-fg": ["--muted-foreground"],
-  "--workbench-hover-bg": ["--design-editor-layer-hover-color", "--accent"],
-  "--workbench-active-bg": ["--design-editor-selection-color", "--accent"],
-  "--workbench-active-fg": [
-    "--design-editor-accent-color",
-    "--accent-foreground",
-  ],
-  "--workbench-accent": ["--design-editor-accent-color", "--primary"],
-  "--workbench-button-bg": ["--design-editor-control-bg", "--background"],
-  "--workbench-button-fg": ["--foreground"],
-  "--workbench-selection-bg": ["--design-editor-selection-color", "--accent"],
-  "--workbench-dirty": ["--warning", "--destructive"],
-};
-
-function normalizeThemeColorValue(value: string): string {
-  const trimmed = value.trim();
-  if (!trimmed) return "";
-  if (/^-?\d+(\.\d+)?\s+-?\d+(\.\d+)?%/.test(trimmed)) {
-    return `hsl(${trimmed})`;
-  }
-  return trimmed;
-}
-
-function resolveCssColorValue(value: string): string {
-  if (typeof window === "undefined" || typeof document === "undefined") {
-    return value;
-  }
-  const probe = document.createElement("span");
-  probe.style.color = value;
-  probe.style.position = "fixed";
-  probe.style.pointerEvents = "none";
-  probe.style.visibility = "hidden";
-  document.body.appendChild(probe);
-  const resolved = window.getComputedStyle(probe).color;
-  probe.remove();
-  return resolved || value;
-}
-
-function readThemeVar(
-  elementStyles: CSSStyleDeclaration,
-  rootStyles: CSSStyleDeclaration,
-  names: string[],
-): string | undefined {
-  for (const name of names) {
-    const value =
-      elementStyles.getPropertyValue(name) || rootStyles.getPropertyValue(name);
-    const normalized = normalizeThemeColorValue(value);
-    if (normalized) return resolveCssColorValue(normalized);
-  }
-  return undefined;
-}
-
-function readCodeWorkbenchTheme(
-  element: HTMLElement | null,
-): CodeWorkbenchTheme {
-  if (typeof window === "undefined" || !element) {
-    return { colorScheme: "light", values: {} };
-  }
-  const elementStyles = window.getComputedStyle(element);
-  const rootStyles = window.getComputedStyle(document.documentElement);
-  const values: Record<string, string> = {};
-  for (const [targetVar, sourceVars] of Object.entries(WORKBENCH_THEME_VARS)) {
-    const value = readThemeVar(elementStyles, rootStyles, sourceVars);
-    if (value) values[targetVar] = value;
-  }
-  const colorScheme =
-    document.documentElement.classList.contains("dark") ||
-    elementStyles.colorScheme.includes("dark") ||
-    rootStyles.colorScheme.includes("dark")
-      ? "dark"
-      : "light";
-  return { colorScheme, values };
-}
-
 let monacoEnvironmentInstalled = false;
 
 function ensureMonacoEnvironment() {
@@ -210,10 +130,12 @@ function defineMonacoTheme(theme: CodeWorkbenchTheme): string {
       "editorWidget.background": values["--workbench-surface-bg"],
       "editorWidget.border": values["--workbench-border"],
       focusBorder: values["--workbench-accent"],
-    }).filter(
-      (entry): entry is [string, string] =>
-        typeof entry[1] === "string" && entry[1].length > 0,
-    ),
+    })
+      .map(([key, value]) => [key, normalizeMonacoThemeColor(value)] as const)
+      .filter(
+        (entry): entry is [string, string] =>
+          typeof entry[1] === "string" && entry[1].length > 0,
+      ),
   );
   monaco.editor.defineTheme(name, {
     base: dark ? "vs-dark" : "vs",