@agent-native/core-corpus 0.210.0 → 0.210.1-nightly-20261019212919

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 12899
+- template files: 12956

package/corpus/templates/analytics/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","analytics-alert-jobs","analytics-rollup-backfill-jobs","auth","collab","config","core-routes","creative-context","dashboard-report-jobs","db","feature-flags","labs","onboarding","otel","session-replay-retention-jobs","transactional-emails","uptime-monitor-jobs"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

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

@@ -4,6 +4,7 @@ import type { AgentChatMcpOptions } from "@agent-native/core/server";
 // framework's cross-app builtins. `mcp-action-contract.spec.ts` serves this
 // config through the real MCP handler and pins the resulting tools/list.
 export const ANALYTICS_MCP = {
+  connectorCatalog: [],
   externalAgents: { writes: "allowlisted" },
   keyToolNames: [
     "list-sql-dashboards",

package/corpus/templates/assets/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","creative-context","db","labs","onboarding","otel"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/brain/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","brain-jobs","core-routes","db","otel"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/calendar/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","core-routes","db","event-rules","oauth-refresh","otel","transactional-emails"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/chat/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","otel"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/chat/server/plugins/agent-chat.ts

@@ -16,6 +16,7 @@ const INITIAL_TOOL_NAMES = [
 export default createAgentChatPlugin({
   appId: "chat",
   actions: loadActionsFromStaticRegistry(actionsRegistry),
+  mcp: { connectorCatalog: [] },
   initialToolNames: INITIAL_TOOL_NAMES,
   resolveOrgId: async (event) => (await getOrgContext(event)).orgId,
   systemPrompt: `You are the Chat app agent.

package/corpus/templates/clips/.agents/skills/recording/SKILL.md

@@ -16,7 +16,7 @@ Reach for this skill any time you touch the recorder: the record button, the in-
 
 ## Data model touched
 
-- **`recordings`** — the row gets created as soon as the user presses Record or imports a source. Native/file recordings transition `uploading` → `processing` → `ready` (or `failed`). `videoUrl`, `durationMs`, `videoSizeBytes`, `width`, `height`, `hasAudio`, `hasCamera` are populated as the upload streams in. Loom imports use `import-loom-recording` and become ready with either a Clips-hosted MP4 or a Loom embed when MP4 export is unavailable.
+- **`recordings`** — the row gets created as soon as the user presses Record or imports a source. Native/file recordings transition `uploading` → `processing` → `ready` (or `failed`). `videoUrl`, `durationMs`, `videoSizeBytes`, `width`, `height`, `hasAudio`, `hasCamera` are populated as the upload streams in. Loom imports use `import-loom-recording` and become ready with either a Clips-hosted MP4 or a Loom embed when MP4 export is unavailable. YouTube imports go through the same action and are always embeds.
 - **`recordings.storage_mode`** — pins each video recording to `own` or `hosted`; null is legacy. Own storage takes precedence when available. Existing hosted recordings keep using the private Clips bucket even if the user connects Builder later.
 - **`application_state.record-intent`** — the agent writes this when it wants to start a recording. The UI reads and clears it, then prompts for permission.
 - **`application_state.navigation`** — set to `{ view: "record" }` while the recorder is active.
@@ -122,7 +122,7 @@ repoints the row only after verified output is stored; any transcode, audio
 verification, upload, or concurrent-update failure leaves the original URL and
 format untouched.
 
-## Loom import
+## Loom and YouTube import
 
 Direct-video and downloadable Loom MP4 imports use the same pinned storage
 resolution, hosted byte limit, and allowance as recorder uploads. A Loom import
@@ -147,6 +147,21 @@ Reuploaded Loom imports support Clips-native trimming, exports, frame extraction
 and upload-based transcription; ask the user to upload the original video file
 when those capabilities are needed for an embed-backed import.
 
+YouTube links (watch, Shorts, youtu.be, embed) also go through
+`import-loom-recording`. Clips never downloads a YouTube video: the action reads
+YouTube's public oEmbed for the title and thumbnail and creates a `ready` clip
+that plays in YouTube's embedded player. Comments, reactions, chapters, and
+transcript highlighting follow YouTube's playback. oEmbed has no duration, so
+the clip starts with `durationMs` 0 and the first editor to open it records the
+length YouTube's player reports (`set-embed-duration`). A YouTube clip has no
+frames, editing, downloads, or transcription; add its transcript with
+`import-transcript`. Private, removed, and embed-disabled videos fail the import
+with a specific error, and a video that becomes unavailable later shows
+YouTube's reason in the player with a Watch on YouTube link. YouTube's player
+policy forbids drawing anything over its player, so the Clips controls sit below
+it and the clip shows no on-video captions or comment bubbles; never add an
+overlay to the YouTube player.
+
 ## Browser diagnostics and recorder install options
 
 Browser recordings can save bounded, redacted diagnostics through

package/corpus/templates/clips/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","calendar-jobs","config","core-routes","db","feature-flags","labs","onboarding","onboarding-calendar","otel","transactional-email-catalog"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/clips/AGENTS.md

@@ -14,7 +14,7 @@ Use local docs only (no web research): `pnpm action docs-search --query "<topic>
 - Use actions for recording metadata, transcripts, cleanup, chapters, comments, meetings, folders, sharing, and collaboration. Respect access helpers. Keep large media/blob payloads out of SQL, state, settings, and resources; store bytes in configured storage and persist references.
 - For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver. Never hardcode credentials, webhook URLs, private/customer data, or credential-like literals.
 - Recording start/stop/pause are browser gestures requiring user activation; navigate to the recording view instead of using a server action. Prefer native transcripts; cloud transcription is fallback-only. Do not hide a usable transcript after failed metadata work.
-- Use `import-loom-recording` for Loom or direct MP4/WebM URLs. Loom/public transcripts import in the background; request a transcript afterward for direct video. Transactional email claims two-Clip summary work and ends in one sentence.
+- Use `import-loom-recording` for Loom, YouTube, or direct MP4/WebM URLs. Loom/public transcripts import in the background; request a transcript afterward for direct video. Transactional email claims two-Clip summary work and ends in one sentence.
 - `view-screen` may return a transcript preview truncated mid-sentence without an ending marker. When `previewTruncated`, read `get-recording-player-data` before judging completeness or quoting.
 - Clips are unlisted-by-link, not searchable. Only inspect recordings the user owns, viewed, or identified by URL/id. Never use `list-recordings` / `search-recordings` to find another person's clip, answer a date question, or recover a failed lookup; report the failure.
 - Sharing actions control access; passwords/expiry only tighten it. Screen Memory is local-only and disabled by default; raw segments are never uploaded or shared. The one exception is an owner's explicit request: a chosen window of Rewind history is uploaded as an owner-only recording attached to one Clip, that Clip follows its normal share rules, and sharing the Clip shares its earlier screen time with it.

package/corpus/templates/clips/actions/get-recording-player-data.ts

@@ -2,6 +2,12 @@ import { defineAction, embedApp } from "@agent-native/core";
 import { readAppState } from "@agent-native/core/application-state";
 import { buildDeepLink, signShortLivedToken } from "@agent-native/core/server";
 import { resolveAccess, ForbiddenError } from "@agent-native/core/sharing";
+import { getAgentClipReadiness } from "@shared/agent-context";
+import { transcriptContextAt } from "@shared/comment-transcript-context";
+import {
+  embedFramesUnavailableReason,
+  recordingEmbedProvider,
+} from "@shared/embed-provider";
 import { isImageRecording, resolveRecordingKind } from "@shared/recording-kind";
 import { asc, eq } from "drizzle-orm";
 import { z } from "zod";
@@ -130,7 +136,7 @@ function recordingDeepLink(recordingId: string): string {
 
 export default defineAction({
   description:
-    "Fetch everything the player page needs for a recording: metadata, transcript, comments, reactions, chapters, tags, CTAs, the counted-view total, and the caller's effective role. Agent calls receive a bounded transcript chunk; pass transcriptOffset from nextFullTextOffset until it is null to read the complete transcript. Browser player calls receive the full transcript.",
+    "Fetch everything the player page needs for a recording: metadata, transcript, comments, reactions, chapters, tags, CTAs, the counted-view total, and the caller's effective role. Agent calls receive a bounded transcript chunk; pass transcriptOffset from nextFullTextOffset until it is null to read the complete transcript. Agent calls also get media (whether frames exist; a YouTube clip has none) and, on each comment, transcriptContext: the transcript spoken around its videoTimestampMs. Browser player calls receive the full transcript.",
   schema: z.object({
     recordingId: z.string().describe("Recording ID"),
     transcriptOffset: z.coerce.number().int().min(0).optional(),
@@ -316,14 +322,17 @@ export default defineAction({
       !transcript.fullText?.trim() &&
       transcriptSegments.length === 0;
     const transcriptPresentation = resolveTranscriptPresentation(transcript);
-    const agentTranscript =
-      ctx?.caller === "tool" || ctx?.caller === "mcp" || ctx?.caller === "a2a"
-        ? boundTranscriptForAgent({
-            fullText: transcript?.fullText,
-            segments: transcriptSegments,
-            fullTextOffset: args.transcriptOffset,
-          })
-        : null;
+    const isAgentCall =
+      ctx?.caller === "tool" || ctx?.caller === "mcp" || ctx?.caller === "a2a";
+    const embedProvider = recordingEmbedProvider(rec);
+    const readiness = getAgentClipReadiness(rec.status);
+    const agentTranscript = isAgentCall
+      ? boundTranscriptForAgent({
+          fullText: transcript?.fullText,
+          segments: transcriptSegments,
+          fullTextOffset: args.transcriptOffset,
+        })
+      : null;
 
     const resolvedVideoUrl = resolvePlayerVideoUrl(rec, {
       addPasswordToken: access.role !== "owner",
@@ -346,6 +355,21 @@ export default defineAction({
     return {
       role: access.role,
       canComment: canCommentRecording,
+      ...(isAgentCall
+        ? {
+            media: {
+              embedProvider,
+              framesAvailable: !embedProvider && readiness.state === "ready",
+              ...(embedProvider
+                ? {
+                    note: `${embedFramesUnavailableReason(embedProvider)} Each comment carries transcriptContext, the transcript spoken around its videoTimestampMs.`,
+                  }
+                : readiness.instruction
+                  ? { note: readiness.instruction }
+                  : {}),
+            },
+          }
+        : {}),
       viewCount,
       agentViewCount,
       recording: {
@@ -495,6 +519,14 @@ export default defineAction({
         content: c.content,
         mentions: displayCommentMentions(c.mentionsJson),
         videoTimestampMs: c.videoTimestampMs,
+        ...(isAgentCall
+          ? {
+              transcriptContext: transcriptContextAt(
+                transcriptSegments,
+                c.videoTimestampMs,
+              ),
+            }
+          : {}),
         emojiReactionsJson: c.emojiReactionsJson,
         resolved: Boolean(c.resolved),
         createdAt: c.createdAt,

package/corpus/templates/clips/actions/import-loom-recording.ts

@@ -8,6 +8,7 @@ import { uploadFile } from "@agent-native/core/file-upload";
 import { buildDeepLink } from "@agent-native/core/server";
 import { extractLoomVideoId, normalizeLoomShareUrl } from "@shared/loom.js";
 import { MAX_UPLOAD_BYTES } from "@shared/upload-limits.js";
+import { isYouTubeUrl } from "@shared/youtube.js";
 import { and, eq, isNull, ne, or } from "drizzle-orm";
 import { z } from "zod";
 
@@ -49,6 +50,7 @@ import {
   failLoomImport,
 } from "./lib/loom-import-job.js";
 import { validateRecordingScope } from "./lib/recording-scope.js";
+import { importYouTubeVideo } from "./lib/youtube-import.js";
 
 export { enqueueFirstImportEmailIfEligible };
 
@@ -74,7 +76,7 @@ const ImportLoomRecordingSchema = z.object({
     .min(1)
     .max(2048)
     .describe(
-      "Loom share/embed URL, or a direct link to an MP4/WebM video file",
+      "Loom share/embed URL, YouTube video URL, or a direct link to an MP4/WebM video file",
     ),
   title: z
     .string()
@@ -82,7 +84,7 @@ const ImportLoomRecordingSchema = z.object({
     .max(200)
     .optional()
     .describe(
-      "Optional title override; defaults to Loom's oEmbed title when available",
+      "Optional title override; defaults to Loom's or YouTube's oEmbed title when available",
     ),
   folderId: z.string().nullish().describe("Optional folder ID"),
   spaceIds: z
@@ -183,9 +185,13 @@ async function fetchLoomOembed(shareUrl: string) {
 
 export default defineAction({
   description:
-    "Import a public Loom share URL, or a direct link to a video file, into Clips as a playable recording. Loom links create the recording immediately and download/reupload Loom's public MP4 when available, or keep a playable Loom embed when Loom allows playback but not MP4 export; public transcripts are imported in the background. Other direct video links (e.g. an MP4/WebM/MOV hosted by another screen recorder) are downloaded and reuploaded synchronously without transcript metadata — use request-transcript afterward. If storage is not connected, creates a waiting recording that can be retried after storage setup.",
+    "Import a public Loom share URL, a YouTube video URL, or a direct link to a video file, into Clips as a playable recording. YouTube links (watch, Shorts, youtu.be) create a ready clip that plays in YouTube's embedded player: nothing is downloaded, so frames, editing and transcription aren't available, and its transcript has to come from import-transcript. Loom links create the recording immediately and download/reupload Loom's public MP4 when available, or keep a playable Loom embed when Loom allows playback but not MP4 export; public transcripts are imported in the background. Other direct video links (e.g. an MP4/WebM/MOV hosted by another screen recorder) are downloaded and reuploaded synchronously without transcript metadata — use request-transcript afterward. If storage is not connected, creates a waiting recording that can be retried after storage setup.",
   schema: ImportLoomRecordingSchema,
   run: async (args, actionContext) => {
+    // YouTube videos are never downloaded, so they skip storage entirely.
+    if (isYouTubeUrl(args.url)) {
+      return importYouTubeVideo(args, actionContext);
+    }
     const loomId = extractLoomVideoId(args.url);
     const isLoom = Boolean(loomId);
     const loomShareUrl = isLoom ? normalizeLoomShareUrl(args.url) : null;

package/corpus/templates/clips/actions/lib/ensure-recording-filmstrip.ts

@@ -14,6 +14,7 @@ import {
   type FilmstripSpriteGrid,
 } from "../../server/lib/video-filmstrip-sprite.js";
 import { isLoomRecordingSource } from "../../shared/loom.js";
+import { isYouTubeEmbedBackedRecording } from "../../shared/youtube.js";
 import {
   fetchProviderBytes,
   isRemoteProviderUrl,
@@ -97,7 +98,7 @@ export async function ensureRecordingFilmstrip(params: {
   if (rec.status !== "ready") {
     return { recordingId, status: "skipped-not-ready", changed: false };
   }
-  if (isLoomRecordingSource(rec)) {
+  if (isLoomRecordingSource(rec) || isYouTubeEmbedBackedRecording(rec)) {
     return { recordingId, status: "skipped-local-media", changed: false };
   }
   if (!rec.videoUrl) {

package/corpus/templates/clips/actions/lib/ensure-seekable-video.ts

@@ -21,6 +21,7 @@ import {
   type VideoFormat,
 } from "../../server/lib/video-remux.js";
 import { isLoomRecordingSource } from "../../shared/loom.js";
+import { isYouTubeEmbedBackedRecording } from "../../shared/youtube.js";
 
 const PROVIDER_FETCH_TIMEOUT_MS = 60_000;
 
@@ -165,7 +166,7 @@ async function ensureRecordingSeekableInternal(params: {
   if (rec.status !== "ready") {
     return { recordingId, status: "skipped-not-ready", changed: false };
   }
-  if (isLoomRecordingSource(rec)) {
+  if (isLoomRecordingSource(rec) || isYouTubeEmbedBackedRecording(rec)) {
     return { recordingId, status: "skipped-local-media", changed: false };
   }
   if (!rec.videoUrl) {

package/corpus/templates/clips/actions/lib/native-media.ts

@@ -1,10 +1,12 @@
 import { fail } from "@agent-native/core/action";
 
+import { recordingEmbedProvider } from "../../shared/embed-provider.js";
 import { isLoomEmbedBackedRecording } from "../../shared/loom.js";
 import { isImageRecording } from "../../shared/recording-kind.js";
 
 type RecordingMediaLike = {
   sourceAppName?: string | null;
+  sourceWindowTitle?: string | null;
   videoUrl?: string | null;
   kind?: string | null;
 };
@@ -19,6 +21,9 @@ const SCREENSHOT_MESSAGE =
 const LOOM_NATIVE_MEDIA_MESSAGE =
   "This action requires a Clips-hosted video. This Loom import is embed-backed; reimport it so Clips can store the video file before using native editing, frame extraction, stitching, or upload-based transcription.";
 
+const YOUTUBE_NATIVE_MEDIA_MESSAGE =
+  "This action requires a Clips-hosted video. This clip plays in YouTube's embedded player and Clips stores no copy of it, so editing, frame extraction, stitching, and transcription aren't available. To give it a transcript, import one with import-transcript.";
+
 export function isLoomRecording(recording: RecordingMediaLike): boolean {
   return isLoomEmbedBackedRecording(recording);
 }
@@ -32,14 +37,25 @@ export function assertNativeRecordingMedia(
       statusCode: 422,
     });
   }
-  if (isLoomRecording(recording)) {
-    fail(LOOM_NATIVE_MEDIA_MESSAGE, {
+  const embedProvider = recordingEmbedProvider(recording);
+  if (embedProvider) {
+    fail(
+      embedProvider === "youtube"
+        ? YOUTUBE_NATIVE_MEDIA_MESSAGE
+        : LOOM_NATIVE_MEDIA_MESSAGE,
+      { errorCode: "native_media_required", statusCode: 422 },
+    );
+  }
+}
+
+/** Loom embeds still import Loom's transcript; a YouTube clip has no source. */
+export function assertTranscribableRecordingMedia(
+  recording: RecordingMediaLike,
+): void {
+  if (recordingEmbedProvider(recording) === "youtube") {
+    fail(YOUTUBE_NATIVE_MEDIA_MESSAGE, {
       errorCode: "native_media_required",
       statusCode: 422,
     });
   }
 }
-
-export function nativeMediaRequiredMessage(): string {
-  return LOOM_NATIVE_MEDIA_MESSAGE;
-}

package/corpus/templates/clips/actions/lib/youtube-import.ts

@@ -0,0 +1,247 @@
+import { fail } from "@agent-native/core/action";
+import {
+  writeAppState,
+  writeAppStateForCurrentTab,
+} from "@agent-native/core/application-state";
+import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
+import {
+  extractYouTubeVideoId,
+  YOUTUBE_SOURCE_APP_NAME,
+  youtubeEmbedUrl,
+  youtubeWatchUrl,
+} from "@shared/youtube.js";
+import { z } from "zod";
+
+import { getDb, schema } from "../../server/db/index.js";
+import { trackRecordingCreated } from "../../server/lib/recording-created.js";
+import {
+  getCurrentOwnerEmail,
+  getDefaultRecordingVisibility,
+  nanoid,
+  requireOrganizationAccess,
+  stringifySpaceIds,
+} from "../../server/lib/recordings.js";
+import { validateRecordingScope } from "./recording-scope.js";
+
+export const YOUTUBE_IMPORT_NOTE =
+  "This clip plays in YouTube's embedded player. Clips stores no copy of the video, so there are no frames to extract and nothing to edit or transcribe. Add a transcript with import-transcript (YouTube's own transcript panel text works); comments, chapters and transcript highlighting follow YouTube's playback.";
+
+const YouTubeOembedSchema = z
+  .object({
+    type: z.literal("video"),
+    title: z.string().optional(),
+    author_name: z.string().optional(),
+    width: z.number().nullable().optional(),
+    height: z.number().nullable().optional(),
+    thumbnail_url: z.string().url().optional(),
+  })
+  .passthrough();
+
+type YouTubeOembed = z.infer<typeof YouTubeOembedSchema>;
+
+export type YouTubeImportArgs = {
+  url: string;
+  title?: string;
+  folderId?: string | null;
+  spaceIds?: string[] | null;
+  organizationId?: string;
+  visibility?: "private" | "org" | "public";
+  recordingId?: string;
+};
+
+export async function fetchYouTubeOembed(
+  watchUrl: string,
+): Promise<YouTubeOembed> {
+  const endpoint = new URL("https://www.youtube.com/oembed");
+  endpoint.searchParams.set("url", watchUrl);
+  endpoint.searchParams.set("format", "json");
+
+  let res: Response;
+  try {
+    res = await ssrfSafeFetch(
+      endpoint.href,
+      {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(15_000),
+      },
+      { maxRedirects: 2 },
+    );
+  } catch (err) {
+    fail(
+      `Clips couldn't reach YouTube (${(err as Error)?.message ?? String(err)}). Try again in a moment.`,
+      { errorCode: "youtube_unreachable", statusCode: 502 },
+    );
+  }
+  if (res.status === 401 || res.status === 403) {
+    fail(
+      "This YouTube video is private or its owner doesn't allow playing it outside YouTube, so Clips can't embed it.",
+      { errorCode: "youtube_embed_unavailable", statusCode: 422 },
+    );
+  }
+  if (res.status === 400 || res.status === 404) {
+    fail(
+      "YouTube has no public video at that link. It may have been removed, or the link may be incomplete.",
+      { errorCode: "youtube_video_not_found", statusCode: 404 },
+    );
+  }
+  if (!res.ok) {
+    fail(
+      `YouTube didn't return the video's details (${res.status}). Try again in a moment.`,
+      { errorCode: "youtube_unreachable", statusCode: 502 },
+    );
+  }
+
+  const parsed = YouTubeOembedSchema.safeParse(
+    // coercion-ok: null fails the schema, so a body that isn't JSON fails below as youtube_unreachable
+    await res.json().catch(() => null),
+  );
+  if (!parsed.success) {
+    fail("YouTube returned an unexpected response for that video.", {
+      errorCode: "youtube_unreachable",
+      statusCode: 502,
+    });
+  }
+  return parsed.data;
+}
+
+// oEmbed reports the default embed's size, not the video's, so only its
+// shape is kept: a 16:9 video becomes 1280x720 and a Short 720x1280.
+function playerDimensions(oembed: YouTubeOembed): {
+  width: number;
+  height: number;
+} {
+  const width = oembed.width ?? 0;
+  const height = oembed.height ?? 0;
+  if (!(width > 0 && height > 0)) return { width: 1280, height: 720 };
+  return width >= height
+    ? { width: 1280, height: Math.round((1280 * height) / width) }
+    : { width: Math.round((1280 * width) / height), height: 1280 };
+}
+
+/**
+ * Creates an embed-backed clip for a YouTube video. Only YouTube's public
+ * oEmbed metadata is fetched: YouTube's terms don't allow downloading the
+ * video, so it plays through YouTube's embedded player.
+ */
+export async function importYouTubeVideo(
+  args: YouTubeImportArgs,
+  actionContext: { userEmail?: string | null } | undefined,
+) {
+  const videoId = extractYouTubeVideoId(args.url);
+  if (!videoId) {
+    fail(
+      "That YouTube link doesn't point to a video. Paste a watch, Shorts, or youtu.be link.",
+      { errorCode: "youtube_url_invalid", statusCode: 400 },
+    );
+  }
+  if (args.recordingId) {
+    fail(
+      "YouTube imports finish immediately, so there's nothing to retry. Import the link again instead.",
+      { errorCode: "youtube_retry_unsupported", statusCode: 400 },
+    );
+  }
+
+  const db = getDb();
+  const ownerEmail = getCurrentOwnerEmail();
+  const { organizationId } = await requireOrganizationAccess(
+    args.organizationId,
+  );
+  const spaceIds = await validateRecordingScope(db, {
+    organizationId,
+    ownerEmail,
+    spaceIds: args.spaceIds ?? [],
+    folderId: args.folderId,
+  });
+  const sourceUrl = youtubeWatchUrl(videoId);
+  const videoUrl = youtubeEmbedUrl(videoId);
+  const oembed = await fetchYouTubeOembed(sourceUrl);
+  const title =
+    args.title?.trim() || oembed.title?.trim() || `YouTube video ${videoId}`;
+  const { width, height } = playerDimensions(oembed);
+  const visibility =
+    args.visibility ??
+    (await getDefaultRecordingVisibility(
+      organizationId,
+      actionContext?.userEmail ?? ownerEmail,
+    ));
+  const id = nanoid();
+  const now = new Date().toISOString();
+  const thumbnailUrl = oembed.thumbnail_url ?? null;
+
+  await db.insert(schema.recordings).values({
+    id,
+    organizationId,
+    orgId: organizationId,
+    folderId: args.folderId ?? null,
+    spaceIds: stringifySpaceIds(spaceIds),
+    title,
+    titleSource: args.title ? "manual" : "upload",
+    recordingPlatform: "import",
+    storageMode: null,
+    failureCode: null,
+    failureReason: null,
+    sourceAppName: YOUTUBE_SOURCE_APP_NAME,
+    sourceWindowTitle: sourceUrl,
+    description: "",
+    thumbnailUrl,
+    // Only YouTube's player knows the length; the first editor to open the
+    // clip records it (see set-embed-duration).
+    durationMs: 0,
+    videoUrl,
+    videoFormat: "mp4",
+    videoSizeBytes: 0,
+    width,
+    height,
+    hasAudio: true,
+    hasCamera: false,
+    status: "ready",
+    uploadProgress: 100,
+    visibility,
+    ownerEmail,
+    createdAt: now,
+    updatedAt: now,
+  });
+  trackRecordingCreated({
+    recordingId: id,
+    userId: ownerEmail,
+    platform: "import",
+    source: "import",
+    hasAudio: true,
+    hasCamera: false,
+  });
+
+  await writeAppState(`recording-upload-${id}`, {
+    recordingId: id,
+    status: "ready",
+    progress: 100,
+    videoUrl,
+    provider: "youtube",
+    sourceUrl,
+    durationMs: 0,
+    width,
+    height,
+    hasAudio: true,
+    hasCamera: false,
+    updatedAt: now,
+  });
+  await writeAppState("refresh-signal", { ts: Date.now() });
+  await writeAppStateForCurrentTab("navigate", {
+    view: "recording",
+    recordingId: id,
+  });
+
+  return {
+    recordingId: id,
+    title,
+    status: "ready" as const,
+    provider: "youtube" as const,
+    sourceUrl,
+    videoUrl,
+    embedUrl: videoUrl,
+    thumbnailUrl,
+    durationMs: 0,
+    importMode: "embed" as const,
+    framesAvailable: false,
+    note: YOUTUBE_IMPORT_NOTE,
+  };
+}

package/corpus/templates/clips/actions/request-transcript.ts

@@ -58,7 +58,10 @@ import {
   fetchLoomTranscript,
   loomTranscriptUnavailableMessage,
 } from "./lib/loom-transcript.js";
-import { isLoomRecording } from "./lib/native-media.js";
+import {
+  assertTranscribableRecordingMedia,
+  isLoomRecording,
+} from "./lib/native-media.js";
 import { isLikelyMismatchedTranscriptLanguage } from "./lib/provider-transcript.js";
 import { prepareRecordingTranscriptionAudio } from "./lib/recording-audio-source.js";
 import regenerateSummary from "./regenerate-summary.js";
@@ -1030,11 +1033,12 @@ const requestTranscriptAction = defineAction({
       ),
   }),
   run: async (args, context?: ActionRunContext) => {
-    await assertAccess("recording", args.recordingId, "editor");
+    const access = await assertAccess("recording", args.recordingId, "editor");
 
     const db = getDb();
 
     if (context?.caller === "tool" || context?.caller === "frontend") {
+      assertTranscribableRecordingMedia(access.resource);
       const [existingTranscript] = await db
         .select({
           status: schema.recordingTranscripts.status,
@@ -1199,6 +1203,11 @@ const requestTranscriptAction = defineAction({
       }
     }
 
+    // Past here the transcript comes from the recording's audio. A ready
+    // transcript, such as an imported one on a YouTube clip, was kept above,
+    // so the follow-up job import-transcript queues still fills its summary.
+    assertTranscribableRecordingMedia(access.resource);
+
     if (
       !args.force &&
       existingNativeTranscript &&