diff --git a/.changeset/fix-read-media-video-upload-fallback.md b/.changeset/fix-read-media-video-upload-fallback.md
new file mode 100644
index 0000000000..c3655aac65
--- /dev/null
+++ b/.changeset/fix-read-media-video-upload-fallback.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix ReadMediaFile failing on videos when the provider has no file upload channel — such videos now fall back to inline delivery.
diff --git a/.changeset/prompt-video-inline.md b/.changeset/prompt-video-inline.md
new file mode 100644
index 0000000000..bd3cacc543
--- /dev/null
+++ b/.changeset/prompt-video-inline.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+Videos attached to a prompt — pasted in the TUI or uploaded in the web UI — now reach the model together with the prompt, with no extra tool round trip, and stay playable in the chat after a reload.
diff --git a/apps/kimi-code/src/tui/kimi-tui.ts b/apps/kimi-code/src/tui/kimi-tui.ts
index 464c7237aa..14951c6ed8 100644
--- a/apps/kimi-code/src/tui/kimi-tui.ts
+++ b/apps/kimi-code/src/tui/kimi-tui.ts
@@ -1135,7 +1135,18 @@ export class KimiTUI {
       this.showError(LLM_NOT_SET_MESSAGE);
       return;
     }
-    const extraction = extractMediaAttachments(text, this.imageStore);
+    let extraction: ReturnType<typeof extractMediaAttachments>;
+    try {
+      // Pasted videos are copied into the cache and expand to a `file://`
+      // `video_url` part; the engine resolves (uploads or degrades) them
+      // inside the turn, so submission stays fully synchronous.
+      extraction = extractMediaAttachments(text, this.imageStore);
+    } catch (error) {
+      // A video cache copy failed (unwritable cache dir, vanished source…);
+      // nothing was dispatched.
+      this.showError(`Failed to prepare media attachment: ${formatErrorMessage(error)}`);
+      return;
+    }
     if (!this.validateMediaCapabilities(extraction)) return;
     const session = this.session;
     if (session === undefined) {
diff --git a/apps/kimi-code/src/tui/utils/image-placeholder.ts b/apps/kimi-code/src/tui/utils/image-placeholder.ts
index 56edcee88b..87d53eabc2 100644
--- a/apps/kimi-code/src/tui/utils/image-placeholder.ts
+++ b/apps/kimi-code/src/tui/utils/image-placeholder.ts
@@ -1,17 +1,28 @@
 /**
- * Scan submitted text for media placeholders and produce
- * the `PromptPart[]` we'll send to the SDK prompt endpoint.
+ * Scan submitted text for media placeholders and produce the prompt content
+ * we'll send to the SDK prompt endpoint.
  *
- * Rules:
+ * `extractMediaAttachments` (sync) is the single expansion path for prompts:
+ *   - image placeholders expand to inline image content parts (preceded by a
+ *     compression caption when paste-time compression shrank the bytes — see
+ *     `ImageAttachment.original`);
+ *   - video placeholders are copied into the shared cache (`getCacheDir()`)
+ *     and expand to a `video_url` part pointing at the cache copy with a
+ *     `file://` url. The v1 engine resolves that local reference inside the
+ *     turn — uploading it (the `ms://` inline form) or degrading to a
+ *     `<video path>` tag the model reads with `ReadMediaFile` — before the
+ *     prompt lands in history.
+ *
+ * `rewriteMediaPlaceholders` is the separate text channel for slash-command
+ * args (`/skill`, plugin commands): those are plain text, so media is rendered
+ * as a `<video|image path="…">` tag / plain-text reference into cache-dir
+ * copies the model opens with `ReadMediaFile`.
+ *
+ * Rules for both:
  *   - Only placeholders that resolve against `store` get extracted.
  *     A literal `[image #999 ...]` the user typed themselves stays in
  *     the text (we can't hallucinate files for it).
- *   - Order is preserved for text/image/video segments. Image placeholders
- *     expand to image content parts so the prompt reaches the provider
- *     without relying on a model tool call. Video placeholders are copied
- *     into the shared cache (`getCacheDir()`) and expand to file-path tags,
- *     so `ReadMediaFile` — and the provider's `VideoUploader` — own video
- *     upload behavior instead of base64-inlining here.
+ *   - Order is preserved for text/image/video segments.
  *   - Adjacent text segments are flattened — empty / whitespace-only
  *     segments drop out so we never emit `{type:'text', text:' '}`
  *     noise between two media parts.
@@ -20,6 +31,7 @@
 import { randomUUID } from 'node:crypto';
 import { copyFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 import type { PromptPart } from '@moonshot-ai/kimi-code-sdk';
 import { buildImageCompressionCaption } from '@moonshot-ai/kimi-code-sdk';
@@ -71,8 +83,10 @@ export function extractMediaAttachments(
     const before = text.slice(cursor, match.index);
     pushText(parts, before);
     if (attachment.kind === 'video') {
+      // Copy the paste into the shared cache and reference it by a `file://`
+      // url; the engine resolves (uploads or degrades) it inside the turn.
       const cachePath = materializeVideoToCache(attachment);
-      pushText(parts, formatMediaTag('video', cachePath));
+      parts.push(videoPartForCachePath(cachePath));
       videoAttachmentIds.push(id);
     } else {
       // Paste-time compression is announced next to the image so the model
@@ -195,6 +209,18 @@ function imagePartForAttachment(att: ImageAttachment): PromptPart {
   };
 }
 
+/**
+ * A `video_url` prompt part pointing at a cache copy by `file://` url. The v1
+ * engine resolves the local reference in-turn (upload → `ms://`, or degrade to
+ * a `<video path>` tag) before it reaches the model or the persisted history.
+ */
+function videoPartForCachePath(cachePath: string): PromptPart {
+  return {
+    type: 'video_url',
+    videoUrl: { url: pathToFileURL(cachePath).href },
+  };
+}
+
 function materializeVideoToCache(att: VideoAttachment, escapeProofName = false): string {
   const cacheDir = getCacheDir();
   mkdirSync(cacheDir, { recursive: true });
diff --git a/apps/kimi-code/test/tui/input/image-placeholder.test.ts b/apps/kimi-code/test/tui/input/image-placeholder.test.ts
index 477727293a..85755641c6 100644
--- a/apps/kimi-code/test/tui/input/image-placeholder.test.ts
+++ b/apps/kimi-code/test/tui/input/image-placeholder.test.ts
@@ -1,6 +1,7 @@
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { describe, it, expect } from 'vitest';
 
@@ -40,16 +41,17 @@ function makeTempDir(): string {
   return mkdtempSync(join(tmpdir(), 'kimi-src-'));
 }
 
-type TextPart = { type: 'text'; text: string };
+type VideoUrlPart = { type: 'video_url'; videoUrl: { url: string } };
 
+// Prompt-attached videos are emitted as a `video_url` part whose url is a
+// local `file://` reference to the cache copy; decode it back to a filesystem
+// path for assertions.
 function videoPathFromParts(parts: unknown[]): string {
-  const text = parts
-    .filter((p): p is TextPart => (p as TextPart).type === 'text')
-    .map((p) => p.text)
-    .join('');
-  const m = /<video path="([^"]+)"><\/video>/.exec(text);
-  if (!m) throw new Error(`no video tag found in: ${text}`);
-  return m[1]!;
+  const part = parts.find(
+    (p): p is VideoUrlPart => (p as VideoUrlPart).type === 'video_url',
+  );
+  if (!part) throw new Error(`no video_url part found in: ${JSON.stringify(parts)}`);
+  return fileURLToPath(part.videoUrl.url);
 }
 
 describe('extractMediaAttachments', () => {
@@ -135,26 +137,27 @@ describe('extractMediaAttachments', () => {
     });
   });
 
-  it('escapes media paths in generated tags', () => {
+  it('keeps the video label (including special chars) in the cache path', () => {
     const { cleanup } = setupTempCache();
     const srcDir = makeTempDir();
     try {
       const srcVideo = join(srcDir, 'source.mp4');
       writeFileSync(srcVideo, 'x');
       const store = new ImageAttachmentStore();
-      // The filename drives the cache label; `&` must be escaped in the attribute.
+      // The filename drives the cache label; `&` is a valid path char the cache
+      // copy keeps verbatim (the engine escapes it if it later renders a tag).
       const att = store.addVideo('video/mp4', srcVideo, 'a&b.mp4');
       const r = extractMediaAttachments(att.placeholder, store);
       expect(r.parts).toHaveLength(1);
-      const text = (r.parts[0] as TextPart).text;
-      expect(text).toMatch(/<video path="[^"]+a&amp;b\.mp4"><\/video>/);
+      expect((r.parts[0] as VideoUrlPart).type).toBe('video_url');
+      expect(videoPathFromParts(r.parts).endsWith('a&b.mp4')).toBe(true);
     } finally {
       cleanup();
       rmSync(srcDir, { recursive: true, force: true });
     }
   });
 
-  it('copies video placeholders into the cache and emits cache-path tags', () => {
+  it('copies video placeholders into the cache and emits a file:// video_url part', () => {
     const { cleanup } = setupTempCache();
     const srcDir = makeTempDir();
     try {
@@ -165,8 +168,11 @@ describe('extractMediaAttachments', () => {
       const r = extractMediaAttachments(att.placeholder, store);
       expect(r.hasMedia).toBe(true);
       expect(r.videoAttachmentIds).toEqual([1]);
+      const part = r.parts[0] as VideoUrlPart;
+      expect(part.type).toBe('video_url');
+      expect(part.videoUrl.url.startsWith('file:')).toBe(true);
       const cachePath = videoPathFromParts(r.parts);
-      // The tag points at the cache, not the original source path.
+      // The part points at the cache copy, not the original source path.
       expect(cachePath.startsWith(getCacheDir())).toBe(true);
       expect(cachePath).not.toBe(srcVideo);
       expect(readFileSync(cachePath, 'utf8')).toBe('video-data');
diff --git a/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts b/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts
index 9fe501d9e0..4ef39560c8 100644
--- a/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts
+++ b/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts
@@ -157,7 +157,8 @@ function makeSession(overrides: Record<string, unknown> = {}) {
     id: 'ses-1',
     model: 'k2',
     summary: { title: null },
-    prompt: vi.fn(async () => {}),
+    prompt: vi.fn(async (_input: unknown) => {}),
+    compact: vi.fn(async () => {}),
     steer: vi.fn(async () => {}),
     init: vi.fn(async () => {}),
     startBtw: vi.fn(async () => 'agent-btw'),
@@ -1554,6 +1555,63 @@ command = "vim"
     expect(transcript).not.toContain('review');
   });
 
+  it('sends a pasted video as a file:// video_url part', async () => {
+    const { driver, session } = await makeDriver();
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const dir = await mkdtemp(join(tmpdir(), 'tui-video-'));
+    try {
+      const srcVideo = join(dir, 'clip.mp4');
+      await writeFile(srcVideo, 'video-bytes');
+      const attachment = imageStore.addVideo('video/mp4', srcVideo);
+
+      // Submission is fully synchronous: the paste is copied to the cache and
+      // referenced by a `file://` video_url the engine resolves in-turn.
+      driver.handleUserInput(`watch ${attachment.placeholder}`);
+
+      const parts = vi.mocked(session.prompt).mock.calls[0]?.[0] as
+        | Array<{
+            type: string;
+            text?: string;
+            videoUrl?: { url: string };
+          }>
+        | undefined;
+      expect(parts?.[0]).toEqual({ type: 'text', text: 'watch ' });
+      expect(parts?.[1]?.type).toBe('video_url');
+      expect(parts?.[1]?.videoUrl?.url).toMatch(/^file:\/\/.*clip\.mp4$/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('queues a pasted video (file:// part) while a turn is streaming', async () => {
+    const session = makeSession();
+    const { driver } = await makeDriver(session);
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const dir = await mkdtemp(join(tmpdir(), 'tui-video-'));
+    try {
+      const srcVideo = join(dir, 'clip.mp4');
+      await writeFile(srcVideo, 'video-bytes');
+      const attachment = imageStore.addVideo('video/mp4', srcVideo);
+      driver.state.appState.streamingPhase = 'waiting';
+
+      driver.handleUserInput(`describe ${attachment.placeholder}`);
+
+      expect(session.prompt).not.toHaveBeenCalled();
+      expect(driver.state.queuedMessages).toHaveLength(1);
+      const queued = driver.state.queuedMessages[0];
+      const parts = queued?.parts as Array<{ type: string; text?: string; videoUrl?: { url: string } }>;
+      expect(parts?.[0]).toEqual({ type: 'text', text: 'describe ' });
+      expect(parts?.[1]?.type).toBe('video_url');
+      expect(parts?.[1]?.videoUrl?.url).toMatch(/^file:\/\/.*clip\.mp4$/);
+
+      driver.sendQueuedMessage(session, queued!);
+      expect(session.prompt).toHaveBeenCalledWith(parts);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+
   it('sends pasted image placeholders as image content parts', async () => {
     const { driver, session } = await makeDriver();
     const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
diff --git a/apps/kimi-web/src/api/daemon/mappers.ts b/apps/kimi-web/src/api/daemon/mappers.ts
index 5eeda29e08..a9e9c03be6 100644
--- a/apps/kimi-web/src/api/daemon/mappers.ts
+++ b/apps/kimi-web/src/api/daemon/mappers.ts
@@ -133,7 +133,7 @@ function toAppImageSource(src: WireImageSource): ImageSource {
   if (src.kind === 'file') {
     return { kind: 'file', fileId: src.file_id };
   }
-  return { kind: 'url', url: src.url };
+  return { kind: 'url', url: src.url, id: src.id };
 }
 
 export function toAppMessageContent(wire: WireMessageContent): AppMessageContent {
@@ -229,7 +229,7 @@ function toWireMessageContent(app: AppMessageContent): WireMessageContent {
       } else if (src.kind === 'file') {
         wireSrc = { kind: 'file', file_id: src.fileId };
       } else {
-        wireSrc = { kind: 'url', url: src.url };
+        wireSrc = { kind: 'url', url: src.url, id: src.id };
       }
       return { type: app.type, source: wireSrc };
     }
diff --git a/apps/kimi-web/src/api/daemon/wire.ts b/apps/kimi-web/src/api/daemon/wire.ts
index 900d98bcf0..bb87f3e3c0 100644
--- a/apps/kimi-web/src/api/daemon/wire.ts
+++ b/apps/kimi-web/src/api/daemon/wire.ts
@@ -193,7 +193,7 @@ export type WireMessageContent =
   | { type: 'thinking'; thinking: string; signature?: string };
 
 export type WireImageSource =
-  | { kind: 'url'; url: string }
+  | { kind: 'url'; url: string; id?: string }
   | { kind: 'base64'; media_type: string; data: string }
   | { kind: 'file'; file_id: string };
 
diff --git a/apps/kimi-web/src/api/types.ts b/apps/kimi-web/src/api/types.ts
index 5c34d26ccb..6c4679f165 100644
--- a/apps/kimi-web/src/api/types.ts
+++ b/apps/kimi-web/src/api/types.ts
@@ -156,7 +156,7 @@ export type AppMessageContent =
   | { type: 'unknown'; raw: unknown };
 
 export type ImageSource =
-  | { kind: 'url'; url: string }
+  | { kind: 'url'; url: string; id?: string }
   | { kind: 'base64'; mediaType: string; data: string }
   | { kind: 'file'; fileId: string };
 
diff --git a/apps/kimi-web/src/components/FilePreview.vue b/apps/kimi-web/src/components/FilePreview.vue
index 1888c2127d..8f21e75307 100644
--- a/apps/kimi-web/src/components/FilePreview.vue
+++ b/apps/kimi-web/src/components/FilePreview.vue
@@ -98,7 +98,7 @@ const rootRef = ref<HTMLElement | null>(null);
 // Content type detection
 // ---------------------------------------------------------------------------
 
-type ContentKind = 'markdown' | 'json' | 'html' | 'pdf' | 'csv' | 'image' | 'text' | 'binary';
+type ContentKind = 'markdown' | 'json' | 'html' | 'pdf' | 'csv' | 'image' | 'video' | 'text' | 'binary';
 
 const contentKind = computed<ContentKind>(() => {
   const f = props.file;
@@ -113,6 +113,7 @@ const contentKind = computed<ContentKind>(() => {
   if (mime === 'application/pdf' || lowerPath.endsWith('.pdf')) return 'pdf';
   if (mime === 'text/csv' || lang === 'csv' || lowerPath.endsWith('.csv')) return 'csv';
   if (mime.startsWith('image/')) return 'image';
+  if (mime.startsWith('video/')) return 'video';
   if (f.isBinary) return 'binary';
   // text/* and code files
   if (mime.startsWith('text/') || lang !== '') return 'text';
@@ -309,6 +310,14 @@ const imageSrc = computed<string | null>(() => {
   return null;
 });
 
+const videoSrc = computed<string | null>(() => {
+  const f = props.file;
+  if (!f || contentKind.value !== 'video') return null;
+  if (f.sourceUrl) return f.sourceUrl;
+  if (f.encoding === 'base64') return `data:${f.mime};base64,${f.content}`;
+  return null;
+});
+
 const pdfSrc = computed<string | null>(() => {
   const f = props.file;
   if (!f || contentKind.value !== 'pdf') return null;
@@ -626,6 +635,19 @@ function truncatePath(path: string, maxLen = 55): string {
         </div>
       </div>
 
+      <!-- Body: Video -->
+      <div v-else-if="contentKind === 'video'" class="fp-body fp-image-wrap">
+        <template v-if="videoSrc">
+          <video :src="videoSrc" class="fp-image" controls playsinline preload="metadata" />
+        </template>
+        <div v-else class="fp-binary-card">
+          <span class="fp-binary-icon">
+            <Icon name="image-off" size="lg" />
+          </span>
+          <span class="fp-binary-label">{{ t('filePreview.videoNoPreview', { mime: file.mime, size: formatSize(file.size) }) }}</span>
+        </div>
+      </div>
+
       <!-- Body: Text/Code (with line numbers) -->
       <div v-else-if="contentKind === 'text'" class="fp-body fp-code">
         <div class="fp-line-table">
diff --git a/apps/kimi-web/src/composables/useFilePreview.ts b/apps/kimi-web/src/composables/useFilePreview.ts
index dea317f482..f61d98d0b2 100644
--- a/apps/kimi-web/src/composables/useFilePreview.ts
+++ b/apps/kimi-web/src/composables/useFilePreview.ts
@@ -13,6 +13,13 @@ type KimiWebClient = ReturnType<typeof useKimiWebClient>;
 /** Which occupant currently owns the shared right-side detail layer. */
 export type DetailTarget = 'file' | 'diff' | 'thinking' | 'compaction' | 'agent' | 'toolDiff' | 'btw';
 
+/** Whether a url can feed a native <video>/<img> src. A provider reference like
+ *  `ms://…` has no local bytes and only yields a broken player, so it's treated
+ *  as non-loadable and falls through to the no-preview card. */
+export function isPlayableMediaUrl(url: string): boolean {
+  return /^(?:https?:|blob:|data:)/i.test(url);
+}
+
 export interface UseFilePreviewOptions {
   client: KimiWebClient;
   detailTarget: Ref<DetailTarget | null>;
@@ -155,24 +162,25 @@ export function useFilePreview({ client, detailTarget }: UseFilePreviewOptions)
   }
 
   function openMediaPreview(media: ToolMedia): void {
-    if (media.kind !== 'image') return;
+    if (media.kind !== 'image' && media.kind !== 'video') return;
     const seq = ++previewRequestSeq;
     revokeMediaObjectUrl();
     detailTarget.value = 'file';
     previewTarget.value = null;
     previewNormalizedPath.value = null;
     previewError.value = null;
+    const isVideo = media.kind === 'video';
     const base = {
-      path: media.path ?? 'ReadMediaFile image',
+      path: media.path ?? (isVideo ? 'Video' : 'ReadMediaFile image'),
       content: '',
       encoding: 'utf-8' as const,
-      mime: media.mimeType ?? mimeFromDataUrl(media.url) ?? 'image/*',
+      mime: media.mimeType ?? mimeFromDataUrl(media.url) ?? (isVideo ? 'video/*' : 'image/*'),
       isBinary: true,
       size: media.bytes ?? 0,
     };
+    // The raw URL 401s under daemon auth (browsers load media without the
+    // Bearer token), so fetch the bytes with auth and preview a blob URL.
     if (media.fileId) {
-      // The raw getFileUrl 401s under daemon auth (browsers load <img> without
-      // the Bearer token), so fetch the bytes with auth and preview a blob URL.
       previewLoading.value = true;
       previewFile.value = base;
       void getKimiWebApi().getFileBlob(media.fileId).then((blob) => {
@@ -194,7 +202,10 @@ export function useFilePreview({ client, detailTarget }: UseFilePreviewOptions)
       });
     } else {
       previewLoading.value = false;
-      previewFile.value = { ...base, sourceUrl: media.url };
+      // A non-loadable url (e.g. a provider `ms://` reference with no local
+      // bytes) can't feed a <video>/<img> src — leave sourceUrl unset so the
+      // preview shows the no-preview card instead of a broken player.
+      previewFile.value = isPlayableMediaUrl(media.url) ? { ...base, sourceUrl: media.url } : base;
     }
   }
 
diff --git a/apps/kimi-web/src/i18n/locales/en/filePreview.ts b/apps/kimi-web/src/i18n/locales/en/filePreview.ts
index 2eb11d72ec..85ae97edb3 100644
--- a/apps/kimi-web/src/i18n/locales/en/filePreview.ts
+++ b/apps/kimi-web/src/i18n/locales/en/filePreview.ts
@@ -21,6 +21,7 @@ export default {
   actual: 'Actual',
   pdfNoPreview: 'This PDF cannot be embedded here. Download it to view.',
   imageNoPreview: 'Image file · {mime} · {size} · preview unavailable',
+  videoNoPreview: 'Video file · {mime} · {size} · preview unavailable',
   binaryNoPreview: 'Binary file · {mime} · {size} bytes · preview unavailable',
   unknownType: 'unknown type',
   copyCode: 'Copy code',
diff --git a/apps/kimi-web/src/i18n/locales/zh/filePreview.ts b/apps/kimi-web/src/i18n/locales/zh/filePreview.ts
index 0906e93d49..333dd77345 100644
--- a/apps/kimi-web/src/i18n/locales/zh/filePreview.ts
+++ b/apps/kimi-web/src/i18n/locales/zh/filePreview.ts
@@ -21,6 +21,7 @@ export default {
   actual: '原始',
   pdfNoPreview: '无法内嵌预览此 PDF，可以下载后查看',
   imageNoPreview: '图片文件 · {mime} · {size} · 暂不预览',
+  videoNoPreview: '视频文件 · {mime} · {size} · 暂不预览',
   binaryNoPreview: '二进制文件 · {mime} · {size} 字节 · 暂不预览',
   unknownType: '未知类型',
   copyCode: '复制代码',
diff --git a/apps/kimi-web/test/event-reducer.test.ts b/apps/kimi-web/test/event-reducer.test.ts
index f22c51119e..9df96de2ed 100644
--- a/apps/kimi-web/test/event-reducer.test.ts
+++ b/apps/kimi-web/test/event-reducer.test.ts
@@ -302,6 +302,49 @@ describe('reduceAppEvent messageCreated', () => {
     expect(msgs[0]?.content).toEqual(echo.content);
     expect(msgs[0]?.promptId).toBe('p1');
   });
+
+  it('reconciles a structured file-source video echo into the optimistic user message', () => {
+    // The server now echoes an uploaded video back as a structured
+    // `{video, source:{kind:'file'}}` part (mirroring images), not a text tag.
+    // It must collapse into the optimistic file-source copy, not duplicate.
+    const optimistic: AppMessage = {
+      id: 'msg_opt_2',
+      sessionId: 's-vid',
+      role: 'user',
+      content: [
+        { type: 'text', text: 'look at this' },
+        { type: 'video', source: { kind: 'file', fileId: 'f_abc' } },
+      ],
+      createdAt: '2026-06-01T12:00:00.000Z',
+      metadata: { 'kimiWeb.optimisticUserMessage': true },
+    };
+    const echo: AppMessage = {
+      id: 'msg_real',
+      sessionId: 's-vid',
+      role: 'user',
+      content: [
+        { type: 'text', text: 'look at this' },
+        { type: 'video', source: { kind: 'file', fileId: 'f_abc' } },
+      ],
+      createdAt: '2026-06-01T12:00:00.000Z',
+      promptId: 'p1',
+    };
+    const state = {
+      ...createInitialState(),
+      sessions: [makeSession('s-vid', '2026-01-01T00:00:00.000Z')],
+      messagesBySession: { 's-vid': [optimistic] },
+    };
+    const next = reduceAppEvent(
+      state,
+      { type: 'messageCreated', message: echo },
+      { sessionId: 's-vid', seq: 1 },
+    );
+    const msgs = next.messagesBySession['s-vid'] ?? [];
+    expect(msgs).toHaveLength(1);
+    expect(msgs[0]?.id).toBe('msg_opt_2');
+    expect(msgs[0]?.content).toEqual(echo.content);
+    expect(msgs[0]?.promptId).toBe('p1');
+  });
 });
 
 describe('reduceAppEvent taskProgress', () => {
diff --git a/apps/kimi-web/test/turn-logic.test.ts b/apps/kimi-web/test/turn-logic.test.ts
index 83d2445384..7c4557b4cf 100644
--- a/apps/kimi-web/test/turn-logic.test.ts
+++ b/apps/kimi-web/test/turn-logic.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import type { AppMessage, AppMessageContent } from '../src/api/types';
 import { latestTodos } from '../src/composables/latestTodos';
 import { messagesToTurns } from '../src/composables/messagesToTurns';
+import { isPlayableMediaUrl } from '../src/composables/useFilePreview';
 
 function message(
   id: string,
@@ -217,6 +218,50 @@ describe('messagesToTurns', () => {
     ]);
   });
 
+  it('renders a structured file-source video part as a video attachment', () => {
+    // An uploaded video comes back from the message projection as a structured
+    // `{video, source:{kind:'file'}}` part (mirroring images). It resolves to
+    // the authenticated file URL, keyed by the same fileId the preview fetches.
+    const fileId = 'f_01KWK39A0ZC8R2ATZEQMD8716C';
+    const turns = messagesToTurns(
+      [
+        message('u1', 'user', [
+          { type: 'text', text: 'look at this' },
+          { type: 'video', source: { kind: 'file', fileId } },
+        ]),
+      ],
+      [],
+      (id) => `/api/v1/files/${id}`,
+      false,
+    );
+
+    expect(turns).toHaveLength(1);
+    expect(turns[0]).toMatchObject({ role: 'user', text: 'look at this' });
+    expect(turns[0]?.attachments).toEqual([
+      { url: `/api/v1/files/${fileId}`, kind: 'video', fileId },
+    ]);
+  });
+
+  it('leaves url-source video parts untouched', () => {
+    const dataUrl = 'data:video/mp4;base64,AAAA';
+    const turns = messagesToTurns(
+      [
+        message('u1', 'user', [
+          { type: 'video', source: { kind: 'url', url: 'https://example.com/clip.mp4' } },
+          { type: 'video', source: { kind: 'url', url: dataUrl } },
+        ]),
+      ],
+      [],
+      (id) => `/api/v1/files/${id}`,
+      false,
+    );
+
+    expect(turns[0]?.attachments).toEqual([
+      { url: 'https://example.com/clip.mp4', kind: 'video' },
+      { url: dataUrl, kind: 'video' },
+    ]);
+  });
+
   it('renders a non-media file part as a file attachment with name and size', () => {
     const turns = messagesToTurns(
       [
@@ -815,3 +860,23 @@ describe('messagesToTurns cron', () => {
     expect(turns.map((t) => t.role)).toEqual(['user', 'assistant', 'cron', 'assistant']);
   });
 });
+
+describe('isPlayableMediaUrl', () => {
+  // Gates the file-preview media source: a playable url feeds a native
+  // <video>/<img> src; a non-playable one falls through to the no-preview card.
+  it('accepts browser-loadable schemes', () => {
+    expect(isPlayableMediaUrl('https://example.com/clip.mp4')).toBe(true);
+    expect(isPlayableMediaUrl('http://example.com/clip.mp4')).toBe(true);
+    expect(isPlayableMediaUrl('data:video/mp4;base64,AAAA')).toBe(true);
+    expect(isPlayableMediaUrl('blob:https://app/uuid')).toBe(true);
+  });
+
+  it('rejects a provider ms:// reference (no local bytes → no preview)', () => {
+    expect(isPlayableMediaUrl('ms://file-abc123')).toBe(false);
+  });
+
+  it('rejects other non-loadable inputs', () => {
+    expect(isPlayableMediaUrl('/api/v1/files/f_abc')).toBe(false);
+    expect(isPlayableMediaUrl('')).toBe(false);
+  });
+});
diff --git a/packages/agent-core-v2/src/agent/contextMemory/messageProjection.ts b/packages/agent-core-v2/src/agent/contextMemory/messageProjection.ts
index 11df04c4a7..7e48c65995 100644
--- a/packages/agent-core-v2/src/agent/contextMemory/messageProjection.ts
+++ b/packages/agent-core-v2/src/agent/contextMemory/messageProjection.ts
@@ -13,10 +13,18 @@
  * (image/video/audio — e.g. ReadMediaFile) passes the raw kosong content-part
  * array through, the same shape the live `tool.result` event stream carries,
  * so REST consumers can still render the media after reload/resume.
+ *
+ * A user `video_url` part projects to a structured `video` content part so
+ * REST consumers can render it: an internal `kimi-file://<id>?path=…`
+ * reference becomes `{ kind: 'file', file_id }` (the materialization path is
+ * stripped, never leaked to clients); any other url becomes `{ kind: 'url' }`
+ * carrying the provider id. An `audio_url` part still flattens to a text
+ * marker.
  */
 
 import type { Message, MessageContent, MessageRole, ToolUseContent } from './protocolMessage';
 
+import { parseKimiFileUrl } from '#/agent/media/kimiFileUrl';
 import type { ContextMessage } from './types';
 
 function deriveMessageId(sessionId: string, index: number): string {
@@ -41,12 +49,16 @@ function mapContentPart(part: ContextMessage['content'][number]): MessageContent
     case 'image_url':
       return {
         type: 'image',
-        source: { kind: 'url', url: part.imageUrl.url },
+        source: { kind: 'url', url: part.imageUrl.url, id: part.imageUrl.id },
       };
     case 'audio_url':
       return { type: 'text', text: `[audio:${part.audioUrl.url}]` };
-    case 'video_url':
-      return { type: 'text', text: `[video:${part.videoUrl.url}]` };
+    case 'video_url': {
+      const ref = parseKimiFileUrl(part.videoUrl.url);
+      return ref !== undefined
+        ? { type: 'video', source: { kind: 'file', file_id: ref.fileId } }
+        : { type: 'video', source: { kind: 'url', url: part.videoUrl.url, id: part.videoUrl.id } };
+    }
   }
 }
 
diff --git a/packages/agent-core-v2/src/agent/contextMemory/protocolMessage.ts b/packages/agent-core-v2/src/agent/contextMemory/protocolMessage.ts
index 6db5d65720..f7e8791f1b 100644
--- a/packages/agent-core-v2/src/agent/contextMemory/protocolMessage.ts
+++ b/packages/agent-core-v2/src/agent/contextMemory/protocolMessage.ts
@@ -4,6 +4,11 @@
  * Defined next to `messageProjection.ts`, which projects `ContextMessage`
  * into this shape; consumed by the `messageLegacy` edge adapter and the
  * transports.
+ *
+ * Media sources come in three kinds: `url`, `base64`, and `file` (a daemon
+ * upload id). The `url` kind optionally pairs an `id` — the provider-issued
+ * file id behind a reference such as `ms://…` — forwarded on the wire when
+ * the provider keys media by id.
  */
 
 import { z } from 'zod';
@@ -36,7 +41,11 @@ export const toolResultContentSchema = z.object({
 export type ToolResultContent = z.infer<typeof toolResultContentSchema>;
 
 export const imageSourceSchema = z.discriminatedUnion('kind', [
-  z.object({ kind: z.literal('url'), url: z.string().min(1) }),
+  z.object({
+    kind: z.literal('url'),
+    url: z.string().min(1),
+    id: z.string().min(1).optional(),
+  }),
   z.object({
     kind: z.literal('base64'),
     media_type: z.string().min(1),
diff --git a/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts b/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts
index 006bd39eaf..fa4d9daa94 100644
--- a/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts
+++ b/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts
@@ -9,7 +9,11 @@
  * resolved from `IModelCatalog`: one primary `requester.request(input, signal,
  * params)` attempt plus projection rebuilds for request structure or media
  * compatibility; general retry policy remains in the loop's `stepRetry`
- * plugin. When a model is configured, `prepareTurnConfig` snapshots the
+ * plugin. Before each request the projected messages pass through `media`'s
+ * video resolver, which rewrites every `kimi-file://` prompt-video reference
+ * to a provider-acceptable part (uploaded `ms://`, inline base64, or a
+ * `<video path>` tag) so the internal reference never reaches the wire. When a
+ * model is configured, `prepareTurnConfig` snapshots the
  * model, effective thinking effort, and system prompt at the turn boundary
  * so loop telemetry and every request in that turn share one configuration.
  * Forwards streamed `part` events to the caller's `onPart`
@@ -38,6 +42,7 @@ import {
 import { IAgentProfileService, type ProfileModelContext } from '#/agent/profile/profile';
 import { IAgentToolRegistryService } from '#/agent/toolRegistry/toolRegistry';
 import { IAgentToolSelectService } from '#/agent/toolSelect/toolSelect';
+import { IAgentVideoResolverService } from '#/agent/media/videoResolver';
 import { IAgentUsageService } from '#/agent/usage/usage';
 import { IConfigService } from '#/app/config/config';
 import { IEventBus } from '#/app/event/eventBus';
@@ -149,6 +154,7 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
     @IAgentContextSizeService private readonly contextSize: IAgentContextSizeService,
     @IAgentToolRegistryService private readonly tools: IAgentToolRegistryService,
     @IAgentToolSelectService private readonly toolSelect: IAgentToolSelectService,
+    @IAgentVideoResolverService private readonly videoResolver: IAgentVideoResolverService,
     @IAgentProfileService private readonly profile: IAgentProfileService,
     @IAgentUsageService private readonly usage: IAgentUsageService,
     @IConfigService private readonly config: IConfigService,
@@ -299,7 +305,15 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
 
     const run = async (projection: RequestProjection): Promise<AgentLLMRequestFinish> => {
       onRequestTrace(undefined);
-      const input = requestInput(projection);
+      const projected = requestInput(projection);
+      const input = {
+        ...projected,
+        messages: await this.videoResolver.resolve(
+          projected.messages,
+          request.requester,
+          signal,
+        ),
+      };
       const fields =
         projection === 'normal'
           ? request.logFields
diff --git a/packages/agent-core-v2/src/agent/media/kimiFileUrl.ts b/packages/agent-core-v2/src/agent/media/kimiFileUrl.ts
new file mode 100644
index 0000000000..567eeb086d
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/kimiFileUrl.ts
@@ -0,0 +1,50 @@
+/**
+ * `media` domain (L4) — the `kimi-file://` internal video reference.
+ *
+ * A prompt video uploaded to `/files` enters context memory as a `video_url`
+ * part carrying `kimi-file://<fileId>?path=<encoded absolute path>`: `fileId`
+ * addresses the daemon upload the request-time resolver reads bytes from, and
+ * the optional `?path=` names the edge-materialized copy the model opens with
+ * `ReadMediaFile` when the video cannot be uploaded or inlined. The reference
+ * never reaches the provider wire — the resolver rewrites it first. Pure
+ * helpers; no scoped service.
+ */
+
+const KIMI_FILE_SCHEME = 'kimi-file://';
+const PATH_QUERY = '?path=';
+
+export interface KimiFileRef {
+  readonly fileId: string;
+  readonly path?: string;
+}
+
+export function isKimiFileUrl(url: string): boolean {
+  return url.startsWith(KIMI_FILE_SCHEME);
+}
+
+export function buildKimiFileUrl(fileId: string, path?: string): string {
+  const base = `${KIMI_FILE_SCHEME}${fileId}`;
+  return path === undefined || path.length === 0
+    ? base
+    : `${base}${PATH_QUERY}${encodeURIComponent(path)}`;
+}
+
+export function parseKimiFileUrl(url: string): KimiFileRef | undefined {
+  if (!url.startsWith(KIMI_FILE_SCHEME)) return undefined;
+  const rest = url.slice(KIMI_FILE_SCHEME.length);
+  const queryAt = rest.indexOf(PATH_QUERY);
+  if (queryAt === -1) {
+    return rest.length > 0 ? { fileId: rest } : undefined;
+  }
+  const fileId = rest.slice(0, queryAt);
+  if (fileId.length === 0) return undefined;
+  const encoded = rest.slice(queryAt + PATH_QUERY.length);
+  if (encoded.length === 0) return { fileId };
+  let path: string;
+  try {
+    path = decodeURIComponent(encoded);
+  } catch {
+    return { fileId };
+  }
+  return { fileId, path };
+}
diff --git a/packages/agent-core-v2/src/agent/media/mediaToolsRegistrar.ts b/packages/agent-core-v2/src/agent/media/mediaToolsRegistrar.ts
index 60e3833d07..30848ad7a4 100644
--- a/packages/agent-core-v2/src/agent/media/mediaToolsRegistrar.ts
+++ b/packages/agent-core-v2/src/agent/media/mediaToolsRegistrar.ts
@@ -11,7 +11,11 @@
  * service re-invokes {@link registerMediaTools} when the model alias or its
  * media capabilities differ from what it last registered (rebinding the
  * video uploader to the new model, and dropping the tool when the model
- * loses media input).
+ * loses media input). The `inlineVideoSupported` flag rides the same
+ * refresh: it is derived from the model's protocol because only the OpenAI
+ * family drops inline video on the wire — every other protocol that
+ * converts `video_url` takes the inline fallback when no upload hook
+ * exists.
  *
  * `AgentLifecycleService.create` force-instantiates this service right after
  * the builtin-tools registrar, before any `opts.binding` bind runs, so the
@@ -103,6 +107,7 @@ export class AgentMediaToolsRegistrar extends Disposable implements IAgentMediaT
           protocol: model?.protocol,
         },
       }),
+      inlineVideoSupported: model?.protocol !== 'openai' && model?.protocol !== 'openai_responses',
       telemetry: this.telemetry,
     });
   }
diff --git a/packages/agent-core-v2/src/agent/media/registerMediaTools.ts b/packages/agent-core-v2/src/agent/media/registerMediaTools.ts
index 9c68272ec4..10f57281f8 100644
--- a/packages/agent-core-v2/src/agent/media/registerMediaTools.ts
+++ b/packages/agent-core-v2/src/agent/media/registerMediaTools.ts
@@ -32,6 +32,7 @@ export interface RegisterMediaToolsDeps {
   readonly capabilities: ModelCapability;
   readonly videoUploader?: VideoUploader;
   readonly telemetry?: ITelemetryService;
+  readonly inlineVideoSupported?: boolean;
 }
 
 export function registerMediaTools(
@@ -49,6 +50,7 @@ export function registerMediaTools(
       deps.capabilities,
       deps.videoUploader,
       deps.telemetry,
+      deps.inlineVideoSupported,
     ),
   );
 }
@@ -60,9 +62,9 @@ export function createVideoUploader(
   const uploadVideo = requester?.uploadVideo;
   if (uploadVideo === undefined) return undefined;
   const bound = uploadVideo.bind(requester);
-  if (telemetry === undefined) return (input) => bound(input);
+  if (telemetry === undefined) return (input, options) => bound(input, options);
 
-  return async (input) => {
+  return async (input, options) => {
     const startedAt = Date.now();
     const base = {
       ...telemetry.props,
@@ -76,7 +78,7 @@ export function createVideoUploader(
       }
     };
     try {
-      const part = await bound(input);
+      const part = await bound(input, options);
       track({ ...base, outcome: 'success', duration_ms: Date.now() - startedAt });
       return part;
     } catch (error) {
diff --git a/packages/agent-core-v2/src/agent/media/tools/read-media.ts b/packages/agent-core-v2/src/agent/media/tools/read-media.ts
index f8f7f93380..5d4d79f0a5 100644
--- a/packages/agent-core-v2/src/agent/media/tools/read-media.ts
+++ b/packages/agent-core-v2/src/agent/media/tools/read-media.ts
@@ -29,6 +29,18 @@
  * Path safety: goes through the shared path access resolver used by
  * Read/Write/Edit.
  *
+ * Videos are delivered through the provider's upload channel when one is
+ * bound, falling back to an inline base64 part when the channel exists but
+ * fails at runtime (no files endpoint, network/server failure) — a failed
+ * upload must not turn the whole read into an error. The same fallback
+ * covers providers with no upload hook at all, as long as their protocol
+ * converts `video_url` (`inlineVideoSupported`, computed from the model's
+ * protocol at registration); when the wire would drop the inline payload
+ * anyway (the OpenAI family), the by-design no-hook error
+ * (`VideoUploadUnsupportedError`) surfaces instead. Auth rejections
+ * (`provider.auth_error` / 401 / 403) always surface, because they drive
+ * credential refresh rather than mask a bad token.
+ *
  * Registration is capability-gated by `registerMediaTools`: this tool is
  * only registered when the active model supports image or video input.
  */
@@ -36,6 +48,8 @@
 import type { ModelCapability } from '#/kosong/contract/capability';
 import type { ContentPart, VideoURLPart } from '#/kosong/contract/message';
 import type { VideoUploadInput as ProviderVideoUploadInput } from '#/kosong/contract/provider';
+import { VideoUploadUnsupportedError } from '#/kosong/contract/errors';
+import { inlineVideoPart, isVideoUploadAuthError } from '#/agent/media/videoUpload';
 import type { ITelemetryService } from '#/app/telemetry/telemetry';
 import { z } from 'zod';
 
@@ -79,7 +93,10 @@ const MAX_MEDIA_BYTES = MAX_MEDIA_MEGABYTES * 1024 * 1024;
 
 export type VideoUploadInput = ProviderVideoUploadInput;
 
-export type VideoUploader = (input: VideoUploadInput) => Promise<VideoURLPart>;
+export type VideoUploader = (
+  input: VideoUploadInput,
+  options?: { readonly signal?: AbortSignal },
+) => Promise<VideoURLPart>;
 
 
 export const ReadMediaFileInputSchema = z.object({
@@ -237,11 +254,21 @@ function buildFullResolutionLimitError(path: string, finalBytes: number): string
   );
 }
 
+function shouldSurfaceVideoUploadError(error: unknown, inlineVideoSupported: boolean): boolean {
+  // No upload hook by design: surfacing the honest error only pays when the
+  // wire would drop an inline payload anyway (the OpenAI family). Protocols
+  // that convert video_url (kimi, anthropic, google-genai, …) take the
+  // inline fallback instead.
+  if (error instanceof VideoUploadUnsupportedError) return !inlineVideoSupported;
+  return isVideoUploadAuthError(error);
+}
+
 export class ReadMediaFileTool implements BuiltinTool<ReadMediaFileInput> {
   readonly name = 'ReadMediaFile' as const;
   readonly description: string;
   readonly parameters: Record<string, unknown> = toInputJsonSchema(ReadMediaFileInputSchema);
   private readonly compressTelemetry: ImageCompressionTelemetry | undefined;
+  private readonly inlineVideoSupported: boolean;
   constructor(
     private readonly fs: IHostFileSystem,
     private readonly env: IHostEnvironment,
@@ -249,10 +276,32 @@ export class ReadMediaFileTool implements BuiltinTool<ReadMediaFileInput> {
     private readonly capabilities: ModelCapability,
     private readonly videoUploader?: VideoUploader,
     telemetry?: ITelemetryService,
+    inlineVideoSupported?: boolean,
   ) {
     this.description = buildDescription(capabilities);
     this.compressTelemetry =
       telemetry === undefined ? undefined : { client: telemetry, source: 'read_media' };
+    this.inlineVideoSupported = inlineVideoSupported ?? false;
+  }
+
+  private async videoContentPart(
+    data: Buffer,
+    mimeType: string,
+    safePath: string,
+  ): Promise<ContentPart> {
+    if (this.videoUploader !== undefined) {
+      try {
+        return await this.videoUploader({
+          data,
+          mimeType,
+          filename: safePath.split(/[\\/]/).at(-1),
+        });
+      } catch (error) {
+        if (shouldSurfaceVideoUploadError(error, this.inlineVideoSupported)) throw error;
+        // Fall through to the inline form.
+      }
+    }
+    return inlineVideoPart(data, mimeType);
   }
 
   resolveExecution(args: ReadMediaFileInput): ToolExecution {
@@ -475,18 +524,8 @@ export class ReadMediaFileTool implements BuiltinTool<ReadMediaFileInput> {
             dimensions = { width: compressed.originalWidth, height: compressed.originalHeight };
           }
         }
-      } else if (this.videoUploader !== undefined) {
-        mediaPart = await this.videoUploader({
-          data,
-          mimeType: fileType.mimeType,
-          filename: safePath.split(/[\\/]/).at(-1),
-        });
       } else {
-        const base64 = data.toString('base64');
-        mediaPart = {
-          type: 'video_url',
-          videoUrl: { url: `data:${fileType.mimeType};base64,${base64}` },
-        };
+        mediaPart = await this.videoContentPart(data, fileType.mimeType, safePath);
       }
 
       const tag = fileType.kind === 'image' ? 'image' : 'video';
diff --git a/packages/agent-core-v2/src/agent/media/videoResolver.ts b/packages/agent-core-v2/src/agent/media/videoResolver.ts
new file mode 100644
index 0000000000..9a279f35ef
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/videoResolver.ts
@@ -0,0 +1,27 @@
+/**
+ * `media` domain (L4) — request-time video reference resolver contract.
+ *
+ * Rewrites the `kimi-file://` video references a prompt carries in the
+ * projected wire messages into a provider-acceptable form (an uploaded
+ * `ms://` reference, an inline base64 `data:` part, or a `<video path>` text
+ * tag) right before the messages reach the provider — so a `kimi-file://` url
+ * never touches the wire. Bound at Agent scope.
+ */
+
+import { createDecorator } from '#/_base/di/instantiation';
+import type { Message } from '#/kosong/contract/message';
+import type { ModelRequester } from '#/kosong/model/modelRequester';
+
+export interface IAgentVideoResolverService {
+  readonly _serviceBrand: undefined;
+
+  resolve(
+    messages: readonly Message[],
+    requester: ModelRequester,
+    signal?: AbortSignal,
+  ): Promise<readonly Message[]>;
+}
+
+export const IAgentVideoResolverService = createDecorator<IAgentVideoResolverService>(
+  'agentVideoResolverService',
+);
diff --git a/packages/agent-core-v2/src/agent/media/videoResolverService.ts b/packages/agent-core-v2/src/agent/media/videoResolverService.ts
new file mode 100644
index 0000000000..ed41445443
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/videoResolverService.ts
@@ -0,0 +1,232 @@
+/**
+ * `media` domain (L4) — `IAgentVideoResolverService` implementation.
+ *
+ * Resolves each `kimi-file://` video reference in the projected wire messages
+ * to a provider-acceptable part right before the request leaves for the wire.
+ * Reads the uploaded bytes through the `file` domain (`IFileService`), uploads
+ * them through the bound model's `ModelRequester.uploadVideo` (wrapped for
+ * `video_upload` telemetry through `createVideoUploader`), and persists the
+ * `(file, provider) → llmFileId` mapping through the `blobStore`
+ * access-pattern store so the upload happens once across a turn's steps,
+ * retries, and media-recovery reprojections. Falls back to an inline base64
+ * `video_url` (protocols that carry it) or a `<video path>` text tag (the
+ * model then opens the edge-materialized copy with `ReadMediaFile`); auth
+ * failures surface so they drive credential refresh instead of masking a bad
+ * token, and an upload interrupted by the step's aborted signal re-throws —
+ * shape-agnostic, since abort rejections vary by provider — so cancellation
+ * ends the request instead of memoizing a degraded fallback for the rest of
+ * the agent's lifetime. Resolution outcomes are memoized per (file, provider)
+ * for step/retry stability — except a transient upload failure, which
+ * degrades only the current request to the tag form so a later step retries
+ * the upload instead of freezing the fallback. Bound at Agent scope.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { InstantiationType } from '#/_base/di/extensions';
+import { LifecycleScope, registerScopedService } from '#/_base/di/scope';
+import { IFileService } from '#/app/file/fileService';
+import { ITelemetryService } from '#/app/telemetry/telemetry';
+import type { ContentPart, Message } from '#/kosong/contract/message';
+import type { ModelRequester } from '#/kosong/model/modelRequester';
+import { IBlobStore } from '#/persistence/interface/blobStore';
+
+import { detectFileType, MEDIA_SNIFF_BYTES } from './file-type';
+import { type KimiFileRef, isKimiFileUrl, parseKimiFileUrl } from './kimiFileUrl';
+import { createVideoUploader } from './registerMediaTools';
+import {
+  inlineVideoPart,
+  inlineVideoSupportedForProtocol,
+  isVideoUploadAuthError,
+  isVideoUploadUnsupportedError,
+} from './videoUpload';
+import { IAgentVideoResolverService } from './videoResolver';
+
+const CACHE_SCOPE = 'video-upload-cache';
+const PROVIDER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const VIDEO_UNAVAILABLE_TEXT =
+  '[video omitted: the uploaded file is no longer available]';
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export class AgentVideoResolverService implements IAgentVideoResolverService {
+  declare readonly _serviceBrand: undefined;
+
+  private readonly resolved = new Map<string, ContentPart>();
+
+  constructor(
+    @IFileService private readonly files: IFileService,
+    @IBlobStore private readonly blobs: IBlobStore,
+    @ITelemetryService private readonly telemetry: ITelemetryService,
+  ) {}
+
+  async resolve(
+    messages: readonly Message[],
+    requester: ModelRequester,
+    signal?: AbortSignal,
+  ): Promise<readonly Message[]> {
+    if (!messages.some(hasKimiFileVideoPart)) return messages;
+
+    let changed = false;
+    const out: Message[] = [];
+    for (const message of messages) {
+      if (!hasKimiFileVideoPart(message)) {
+        out.push(message);
+        continue;
+      }
+      const content: ContentPart[] = [];
+      for (const part of message.content) {
+        const ref =
+          part.type === 'video_url' ? parseKimiFileUrl(part.videoUrl.url) : undefined;
+        content.push(ref === undefined ? part : await this.resolvePart(ref, requester, signal));
+      }
+      out.push({ ...message, content });
+      changed = true;
+    }
+    return changed ? out : messages;
+  }
+
+  private async resolvePart(
+    ref: KimiFileRef,
+    requester: ModelRequester,
+    signal: AbortSignal | undefined,
+  ): Promise<ContentPart> {
+    const model = requester.model;
+    const providerKey = model.providerType ?? model.protocol;
+    const cacheKey = `${ref.fileId}\0${providerKey}`;
+
+    const memoed = this.resolved.get(cacheKey);
+    if (memoed !== undefined) return memoed;
+
+    const { part, memoize } = await this.resolveUncached(ref, requester, cacheKey, signal);
+    if (memoize) this.resolved.set(cacheKey, part);
+    return part;
+  }
+
+  private async resolveUncached(
+    ref: KimiFileRef,
+    requester: ModelRequester,
+    cacheKey: string,
+    signal: AbortSignal | undefined,
+  ): Promise<{ part: ContentPart; memoize: boolean }> {
+    const cachedLlmFileId = await this.readCachedUpload(cacheKey);
+    if (cachedLlmFileId !== undefined) {
+      return {
+        part: { type: 'video_url', videoUrl: { url: `ms://${cachedLlmFileId}`, id: cachedLlmFileId } },
+        memoize: true,
+      };
+    }
+
+    let bytes: Buffer;
+    let filename: string;
+    try {
+      const file = await this.files.get(ref.fileId);
+      bytes = await readStream(file.stream());
+      filename = file.meta.name;
+    } catch {
+      return { part: tag(ref), memoize: true };
+    }
+
+    const fileType = detectFileType(filename, bytes.subarray(0, MEDIA_SNIFF_BYTES), 'media');
+    if (fileType.kind !== 'video') return { part: tag(ref), memoize: true };
+    const mimeType = fileType.mimeType;
+
+    const model = requester.model;
+    if (!model.capabilities.video_in) return { part: tag(ref), memoize: true };
+    const inlineSupported = inlineVideoSupportedForProtocol(model.protocol);
+
+    const uploader = createVideoUploader(requester, {
+      client: this.telemetry,
+      props: {
+        model: model.name,
+        provider_type: model.providerType ?? model.protocol,
+        protocol: model.protocol,
+      },
+    });
+    if (uploader === undefined) {
+      return {
+        part: inlineSupported ? inlineVideoPart(bytes, mimeType) : tag(ref),
+        memoize: true,
+      };
+    }
+
+    try {
+      const uploaded = await uploader({ data: bytes, mimeType, filename }, { signal });
+      const llmFileId = uploaded.videoUrl.id ?? msFileIdFromUrl(uploaded.videoUrl.url);
+      if (llmFileId !== undefined) await this.writeCachedUpload(cacheKey, llmFileId);
+      return { part: uploaded, memoize: true };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      if (isVideoUploadAuthError(error)) throw error;
+      if (isVideoUploadUnsupportedError(error)) {
+        return {
+          part: inlineSupported ? inlineVideoPart(bytes, mimeType) : tag(ref),
+          memoize: true,
+        };
+      }
+      return { part: tag(ref), memoize: false };
+    }
+  }
+
+  private async readCachedUpload(cacheKey: string): Promise<string | undefined> {
+    const data = await this.blobs.get(CACHE_SCOPE, blobKey(cacheKey)).catch(() => undefined);
+    if (data === undefined) return undefined;
+    const llmFileId = textDecoder.decode(data);
+    return PROVIDER_ID_RE.test(llmFileId) ? llmFileId : undefined;
+  }
+
+  private async writeCachedUpload(cacheKey: string, llmFileId: string): Promise<void> {
+    if (!PROVIDER_ID_RE.test(llmFileId)) return;
+    await this.blobs.put(CACHE_SCOPE, blobKey(cacheKey), textEncoder.encode(llmFileId)).catch(
+      () => undefined,
+    );
+  }
+}
+
+function hasKimiFileVideoPart(message: Message): boolean {
+  return message.content.some(
+    (part) => part.type === 'video_url' && isKimiFileUrl(part.videoUrl.url),
+  );
+}
+
+function tag(ref: KimiFileRef): ContentPart {
+  if (ref.path === undefined || ref.path.length === 0) {
+    return { type: 'text', text: VIDEO_UNAVAILABLE_TEXT };
+  }
+  return { type: 'text', text: `<video path="${escapeAttribute(ref.path)}"></video>` };
+}
+
+function msFileIdFromUrl(url: string): string | undefined {
+  if (!url.startsWith('ms://')) return undefined;
+  const id = url.slice('ms://'.length);
+  return id.length > 0 ? id : undefined;
+}
+
+function blobKey(cacheKey: string): string {
+  return createHash('sha256').update(cacheKey).digest('hex');
+}
+
+async function readStream(stream: NodeJS.ReadableStream): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.from(chunk as string | Uint8Array));
+  }
+  return Buffer.concat(chunks);
+}
+
+function escapeAttribute(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+registerScopedService(
+  LifecycleScope.Agent,
+  IAgentVideoResolverService,
+  AgentVideoResolverService,
+  InstantiationType.Delayed,
+  'media',
+);
diff --git a/packages/agent-core-v2/src/agent/media/videoUpload.ts b/packages/agent-core-v2/src/agent/media/videoUpload.ts
new file mode 100644
index 0000000000..e10e3a1fe7
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/videoUpload.ts
@@ -0,0 +1,35 @@
+/**
+ * `media` domain (L4) — shared video-upload fallback helpers.
+ *
+ * The provider video-upload attempt and its graceful fallbacks run in two
+ * places — the `ReadMediaFile` tool (a model tool call) and the request-time
+ * video resolver (a prompt's `kimi-file://` part) — and must agree on which
+ * failures are auth failures (surfaced, never masked into a fallback) and
+ * which protocols carry inline `video_url` on the wire. Pure helpers; no
+ * scoped service.
+ */
+
+import { VideoUploadUnsupportedError } from '#/kosong/contract/errors';
+import type { VideoURLPart } from '#/kosong/contract/message';
+import type { Protocol } from '#/kosong/protocol/protocol';
+import { ProtocolErrors } from '#/kosong/protocol/errors';
+
+export function isVideoUploadAuthError(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  if ((error as { code?: unknown }).code === ProtocolErrors.codes.PROVIDER_AUTH_ERROR) return true;
+  const statusCode = (error as { statusCode?: unknown }).statusCode;
+  return statusCode === 401 || statusCode === 403;
+}
+
+export function isVideoUploadUnsupportedError(error: unknown): error is VideoUploadUnsupportedError {
+  return error instanceof VideoUploadUnsupportedError;
+}
+
+export function inlineVideoSupportedForProtocol(protocol: Protocol): boolean {
+  return protocol !== 'openai' && protocol !== 'openai_responses';
+}
+
+export function inlineVideoPart(data: Uint8Array, mimeType: string): VideoURLPart {
+  const base64 = Buffer.from(data).toString('base64');
+  return { type: 'video_url', videoUrl: { url: `data:${mimeType};base64,${base64}` } };
+}
diff --git a/packages/agent-core-v2/src/index.ts b/packages/agent-core-v2/src/index.ts
index 219c55a51c..6f833e0b32 100644
--- a/packages/agent-core-v2/src/index.ts
+++ b/packages/agent-core-v2/src/index.ts
@@ -428,6 +428,10 @@ export * from '#/agent/mcp/config-schema';
 export * from '#/agent/media/mediaTools';
 export * from '#/agent/media/mediaToolsRegistrar';
 export * from '#/agent/media/registerMediaTools';
+export * from '#/agent/media/kimiFileUrl';
+export * from '#/agent/media/videoUpload';
+export * from '#/agent/media/videoResolver';
+export * from '#/agent/media/videoResolverService';
 import '#/agent/media/configSection';
 export * from '#/agent/media/imageConfigBridge';
 import '#/agent/permissionMode/configSection';
diff --git a/packages/agent-core-v2/src/kosong/contract/errors.ts b/packages/agent-core-v2/src/kosong/contract/errors.ts
index 846c4f64c5..43b9ee5dd7 100644
--- a/packages/agent-core-v2/src/kosong/contract/errors.ts
+++ b/packages/agent-core-v2/src/kosong/contract/errors.ts
@@ -5,6 +5,9 @@
  * the `API*Error` class family, the retry verdict (`isRetryableGenerateError`),
  * the telemetry classification (`ApiErrorKind` / `classifyApiError`), and the
  * status-error normalizer every dialect's error converter funnels through.
+ * Alongside the wire-status classes, `VideoUploadUnsupportedError` marks the
+ * by-design capability gap (provider has no video upload hook) so callers
+ * can tell it apart from an upload that failed at runtime.
  *
  * Abort has exactly one standard shape here: the DOMException built by
  * `createAbortError`. Provider error converters must run the `throwIfAbortError`
@@ -29,6 +32,13 @@ export class APIConnectionError extends ChatProviderError {
   }
 }
 
+export class VideoUploadUnsupportedError extends ChatProviderError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'VideoUploadUnsupportedError';
+  }
+}
+
 export class APITimeoutError extends ChatProviderError {
   constructor(message: string) {
     super(message);
diff --git a/packages/agent-core-v2/src/kosong/model/modelRequesterImpl.ts b/packages/agent-core-v2/src/kosong/model/modelRequesterImpl.ts
index dff94ce2ab..6e7d52e260 100644
--- a/packages/agent-core-v2/src/kosong/model/modelRequesterImpl.ts
+++ b/packages/agent-core-v2/src/kosong/model/modelRequesterImpl.ts
@@ -23,7 +23,7 @@
 
 import { AsyncEventQueue } from '#/_base/asyncEventQueue';
 import type { VideoURLPart } from '#/kosong/contract/message';
-import { APIStatusError, isAbortError } from '#/kosong/contract/errors';
+import { APIStatusError, isAbortError, VideoUploadUnsupportedError } from '#/kosong/contract/errors';
 import { generate, type GenerateResult } from '#/kosong/contract/generate';
 import type {
   ChatProvider,
@@ -85,7 +85,7 @@ export class ModelRequesterImpl implements ModelRequester {
   ): Promise<VideoURLPart> {
     const provider = this.resolveChatProvider();
     if (provider.uploadVideo === undefined) {
-      throw new Error(
+      throw new VideoUploadUnsupportedError(
         `Model "${this.model.id}" (protocol=${this.model.protocol}) does not support video upload`,
       );
     }
diff --git a/packages/agent-core-v2/test/agent/llmRequester/llmRequesterService.test.ts b/packages/agent-core-v2/test/agent/llmRequester/llmRequesterService.test.ts
index 53307d2623..a91ddfb3df 100644
--- a/packages/agent-core-v2/test/agent/llmRequester/llmRequesterService.test.ts
+++ b/packages/agent-core-v2/test/agent/llmRequester/llmRequesterService.test.ts
@@ -32,6 +32,7 @@ import { IAgentContextSizeService } from '#/agent/contextSize/contextSize';
 import { IAgentProfileService } from '#/agent/profile/profile';
 import { IAgentToolRegistryService } from '#/agent/toolRegistry/toolRegistry';
 import { IAgentToolSelectService } from '#/agent/toolSelect/toolSelect';
+import { IAgentVideoResolverService } from '#/agent/media/videoResolver';
 import { IAgentUsageService } from '#/agent/usage/usage';
 import { IConfigService } from '#/app/config/config';
 import { type DomainEvent, IEventBus } from '#/app/event/eventBus';
@@ -194,6 +195,7 @@ function createService(
 
   ix.stub(IAgentContextMemoryService, context);
   ix.stub(IAgentToolSelectService, toolSelect);
+  ix.stub(IAgentVideoResolverService, { resolve: async (messages) => messages });
   if (projector === undefined) {
     ix.set(
       IAgentContextProjectorService,
diff --git a/packages/agent-core-v2/test/agent/media/tools/read-media.test.ts b/packages/agent-core-v2/test/agent/media/tools/read-media.test.ts
index 505050106f..0e5a0b7c2a 100644
--- a/packages/agent-core-v2/test/agent/media/tools/read-media.test.ts
+++ b/packages/agent-core-v2/test/agent/media/tools/read-media.test.ts
@@ -9,6 +9,7 @@
 
 import type { ModelCapability } from '#/kosong/contract/capability';
 import type { ContentPart } from '#/kosong/contract/message';
+import { VideoUploadUnsupportedError } from '#/kosong/contract/errors';
 import { Jimp } from 'jimp';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
@@ -172,6 +173,7 @@ function makeTool(
   caps: ModelCapability = capabilities(),
   videoUploader?: VideoUploader,
   telemetry?: ITelemetryService,
+  inlineVideoSupported?: boolean,
 ): ReadMediaFileTool {
   return new ReadMediaFileTool(
     createTestFs(files),
@@ -180,6 +182,7 @@ function makeTool(
     caps,
     videoUploader,
     telemetry,
+    inlineVideoSupported,
   );
 }
 
@@ -684,6 +687,75 @@ describe('ReadMediaFileTool', () => {
     expect(parts[1]).toEqual(uploadResult);
   });
 
+  it('falls back to an inline base64 video part when the upload fails', async () => {
+    const videoUploader = vi.fn<VideoUploader>().mockRejectedValue(new Error('404 route not found'));
+    const result = await execute(
+      makeTool({ '/workspace/clip.mp4': { data: mp4Buffer() } }, capabilities(), videoUploader),
+      { path: '/workspace/clip.mp4' },
+    );
+    expect(result.isError).not.toBe(true);
+    const parts = outputParts(result);
+    expect(videoUploader).toHaveBeenCalledOnce();
+    expect(parts[1]).toEqual({
+      type: 'video_url',
+      videoUrl: { url: `data:video/mp4;base64,${mp4Buffer().toString('base64')}` },
+    });
+  });
+
+  it('surfaces auth rejections from the upload channel instead of falling back', async () => {
+    const videoUploader = vi
+      .fn<VideoUploader>()
+      .mockRejectedValue(Object.assign(new Error('401 Unauthorized'), { statusCode: 401 }));
+    const result = await execute(
+      makeTool({ '/workspace/clip.mp4': { data: mp4Buffer() } }, capabilities(), videoUploader),
+      { path: '/workspace/clip.mp4' },
+    );
+    expect(result.isError).toBe(true);
+    expect(result.output).toContain('401 Unauthorized');
+  });
+
+  it('surfaces the by-design no-hook error instead of falling back to inline', async () => {
+    const videoUploader = vi
+      .fn<VideoUploader>()
+      .mockRejectedValue(
+        new VideoUploadUnsupportedError(
+          'Model "stub" (protocol=openai) does not support video upload',
+        ),
+      );
+    const result = await execute(
+      makeTool({ '/workspace/clip.mp4': { data: mp4Buffer() } }, capabilities(), videoUploader),
+      { path: '/workspace/clip.mp4' },
+    );
+    expect(result.isError).toBe(true);
+    expect(result.output).toContain('does not support video upload');
+  });
+
+  it('falls back to inline for a no-hook provider whose wire carries video', async () => {
+    const videoUploader = vi
+      .fn<VideoUploader>()
+      .mockRejectedValue(
+        new VideoUploadUnsupportedError(
+          'Model "gemini-stub" (protocol=google-genai) does not support video upload',
+        ),
+      );
+    const result = await execute(
+      makeTool(
+        { '/workspace/clip.mp4': { data: mp4Buffer() } },
+        capabilities(),
+        videoUploader,
+        undefined,
+        true,
+      ),
+      { path: '/workspace/clip.mp4' },
+    );
+    expect(result.isError).not.toBe(true);
+    const parts = outputParts(result);
+    expect(parts[1]).toEqual({
+      type: 'video_url',
+      videoUrl: { url: `data:video/mp4;base64,${mp4Buffer().toString('base64')}` },
+    });
+  });
+
   it('rejects empty files', async () => {
     const result = await execute(
       makeTool({ '/workspace/sample.png': { data: pngBuffer(), size: 0 } }),
@@ -864,7 +936,7 @@ describe('createVideoUploader', () => {
     const uploadVideo = vi.fn().mockResolvedValue(uploadResult);
     const uploader = createVideoUploader(modelWith(uploadVideo));
     await expect(uploader!(input)).resolves.toEqual(uploadResult);
-    expect(uploadVideo).toHaveBeenCalledWith(input);
+    expect(uploadVideo).toHaveBeenCalledWith(input, undefined);
   });
 
   it('reports video_upload telemetry on success', async () => {
diff --git a/packages/agent-core-v2/test/agent/media/videoResolver.test.ts b/packages/agent-core-v2/test/agent/media/videoResolver.test.ts
new file mode 100644
index 0000000000..5ce7630ed6
--- /dev/null
+++ b/packages/agent-core-v2/test/agent/media/videoResolver.test.ts
@@ -0,0 +1,308 @@
+import { Readable } from 'node:stream';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { buildKimiFileUrl, parseKimiFileUrl } from '#/agent/media/kimiFileUrl';
+import { AgentVideoResolverService } from '#/agent/media/videoResolverService';
+import type { GetResult, IFileService } from '#/app/file/fileService';
+import type { ITelemetryService } from '#/app/telemetry/telemetry';
+import type { ModelCapability } from '#/kosong/contract/capability';
+import type { Message, VideoURLPart } from '#/kosong/contract/message';
+import type { ModelRequester } from '#/kosong/model/modelRequester';
+import type { Protocol } from '#/kosong/protocol/protocol';
+import type { IBlobStore } from '#/persistence/interface/blobStore';
+
+const FILE_ID = 'file_abc';
+const FALLBACK_PATH = '/cache/file_abc.mp4';
+const VIDEO_BYTES = Buffer.from('tiny fake mp4 bytes');
+const PNG_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00]);
+
+function videoMessage(url: string): Message {
+  return { role: 'user', content: [{ type: 'video_url', videoUrl: { url } }], toolCalls: [] };
+}
+
+function firstPart(messages: readonly Message[]) {
+  return messages[0]!.content[0]!;
+}
+
+function fileService(files: Map<string, { name: string; bytes: Buffer }>): IFileService {
+  return {
+    _serviceBrand: undefined,
+    save: async () => {
+      throw new Error('unused');
+    },
+    delete: async () => {},
+    get: async (fileId): Promise<GetResult> => {
+      const file = files.get(fileId);
+      if (file === undefined) throw new Error(`file not found: ${fileId}`);
+      return {
+        meta: {
+          id: fileId,
+          name: file.name,
+          media_type: 'video/mp4',
+          size: file.bytes.length,
+          created_at: new Date(0).toISOString(),
+        },
+        stream: () => Readable.from([file.bytes]),
+      };
+    },
+  };
+}
+
+function blobStore(): IBlobStore {
+  const data = new Map<string, Uint8Array>();
+  return {
+    _serviceBrand: undefined,
+    put: async (scope, key, bytes) => {
+      data.set(`${scope}/${key}`, bytes);
+    },
+    get: async (scope, key) => data.get(`${scope}/${key}`),
+    getStream: async function* () {},
+    has: async (scope, key) => data.has(`${scope}/${key}`),
+    delete: async (scope, key) => {
+      data.delete(`${scope}/${key}`);
+    },
+    list: async () => [],
+  };
+}
+
+const telemetry = { track2: () => {} } as unknown as ITelemetryService;
+
+function requester(opts: {
+  videoIn?: boolean;
+  protocol?: Protocol;
+  providerType?: string;
+  uploadVideo?: ModelRequester['uploadVideo'];
+}): ModelRequester {
+  return {
+    model: {
+      id: 'm',
+      name: 'stub',
+      aliases: [],
+      protocol: opts.protocol ?? 'openai',
+      headers: {},
+      capabilities: { video_in: opts.videoIn ?? true } as unknown as ModelCapability,
+      maxContextSize: 1000,
+      alwaysThinking: false,
+      providerName: 'p',
+      providerType: opts.providerType ?? 'kimi',
+      authProvider: {} as never,
+    },
+    request: () => {
+      throw new Error('unused');
+    },
+    uploadVideo: opts.uploadVideo,
+  };
+}
+
+function msPart(id: string): VideoURLPart {
+  return { type: 'video_url', videoUrl: { url: `ms://${id}`, id } };
+}
+
+describe('kimiFileUrl', () => {
+  it('round-trips a file id and an escaped materialization path', () => {
+    const url = buildKimiFileUrl('file_1', '/a b/clip.mp4');
+    expect(url).toBe(`kimi-file://file_1?path=${encodeURIComponent('/a b/clip.mp4')}`);
+    expect(parseKimiFileUrl(url)).toEqual({ fileId: 'file_1', path: '/a b/clip.mp4' });
+  });
+
+  it('omits the query when no path is given', () => {
+    expect(buildKimiFileUrl('file_1')).toBe('kimi-file://file_1');
+    expect(parseKimiFileUrl('kimi-file://file_1')).toEqual({ fileId: 'file_1' });
+  });
+
+  it('returns undefined for any non-kimi-file url', () => {
+    expect(parseKimiFileUrl('ms://prov-1')).toBeUndefined();
+    expect(parseKimiFileUrl('data:video/mp4;base64,AAAA')).toBeUndefined();
+    expect(parseKimiFileUrl('https://example.com/clip.mp4')).toBeUndefined();
+  });
+});
+
+describe('AgentVideoResolverService', () => {
+  it('uploads a kimi-file video once and reuses the cached reference on later steps', async () => {
+    const upload = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
+    const resolver = new AgentVideoResolverService(
+      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
+      blobStore(),
+      telemetry,
+    );
+    const req = requester({ uploadVideo: upload });
+    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
+
+    const first = await resolver.resolve([message], req);
+    const second = await resolver.resolve([message], req);
+
+    expect(firstPart(first)).toEqual(msPart('prov-1'));
+    expect(firstPart(second)).toEqual(msPart('prov-1'));
+    expect(upload).toHaveBeenCalledTimes(1);
+  });
+
+  it('reuses a persisted upload across resolver instances without re-uploading', async () => {
+    const files = new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]);
+    const blobs = blobStore();
+    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
+
+    const upload1 = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
+    await new AgentVideoResolverService(fileService(files), blobs, telemetry).resolve(
+      [message],
+      requester({ uploadVideo: upload1 }),
+    );
+
+    const upload2 = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-2'));
+    const out = await new AgentVideoResolverService(fileService(files), blobs, telemetry).resolve(
+      [message],
+      requester({ uploadVideo: upload2 }),
+    );
+
+    expect(firstPart(out)).toEqual(msPart('prov-1'));
+    expect(upload1).toHaveBeenCalledTimes(1);
+    expect(upload2).not.toHaveBeenCalled();
+  });
+
+  it('falls back to a path tag when the model cannot ingest video', async () => {
+    const upload = vi.fn();
+    const out = await new AgentVideoResolverService(
+      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
+      blobStore(),
+      telemetry,
+    ).resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ videoIn: false, uploadVideo: upload }));
+
+    expect(firstPart(out)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
+    expect(upload).not.toHaveBeenCalled();
+  });
+
+  it('inlines base64 for a no-upload provider whose wire carries video', async () => {
+    const out = await new AgentVideoResolverService(
+      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
+      blobStore(),
+      telemetry,
+    ).resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ protocol: 'anthropic', uploadVideo: undefined }));
+
+    expect(firstPart(out)).toEqual({
+      type: 'video_url',
+      videoUrl: { url: `data:video/mp4;base64,${VIDEO_BYTES.toString('base64')}` },
+    });
+  });
+
+  it('tags for a no-upload provider whose wire drops inline video (openai family)', async () => {
+    const out = await new AgentVideoResolverService(
+      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
+      blobStore(),
+      telemetry,
+    ).resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ protocol: 'openai', uploadVideo: undefined }));
+
+    expect(firstPart(out)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
+  });
+
+  it('rethrows an auth failure so it can drive credential refresh', async () => {
+    const upload = vi.fn(async () => {
+      throw Object.assign(new Error('unauthorized'), { statusCode: 401 });
+    });
+    const resolver = new AgentVideoResolverService(
+      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
+      blobStore(),
+      telemetry,
+    );
+
+    await expect(
+      resolver.resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ uploadVideo: upload })),
+    ).rejects.toThrow('unauthorized');
+  });
+
+  it('rethrows a cancelled upload without memoizing the fallback', async () => {
+    const controller = new AbortController();
+    // The rejection is deliberately NOT abort-shaped: the aborted signal alone
+    // must decide cancellation, since abort error shapes vary by provider.
+    const interrupted = vi.fn(async () => {
+      controller.abort();
+      throw new Error('socket closed');
+    });
+    const resolver = new AgentVideoResolverService(
+      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
+      blobStore(),
+      telemetry,
+    );
+    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
+
+    await expect(
+      resolver.resolve([message], requester({ uploadVideo: interrupted }), controller.signal),
+    ).rejects.toThrow('socket closed');
+
+    const retry = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
+    const out = await resolver.resolve([message], requester({ uploadVideo: retry }));
+    expect(firstPart(out)).toEqual(msPart('prov-1'));
+    expect(retry).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries the upload on a later step after a transient failure instead of freezing the tag', async () => {
+    let uploadCalls = 0;
+    const upload = vi.fn(async (): Promise<VideoURLPart> => {
+      uploadCalls += 1;
+      if (uploadCalls === 1) throw new Error('files endpoint unavailable');
+      return msPart('prov-1');
+    });
+    const resolver = new AgentVideoResolverService(
+      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
+      blobStore(),
+      telemetry,
+    );
+    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
+    const req = requester({ uploadVideo: upload });
+
+    const failed = await resolver.resolve([message], req);
+    expect(firstPart(failed)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
+
+    const retried = await resolver.resolve([message], req);
+    expect(firstPart(retried)).toEqual(msPart('prov-1'));
+
+    const memoed = await resolver.resolve([message], req);
+    expect(firstPart(memoed)).toEqual(msPart('prov-1'));
+    expect(upload).toHaveBeenCalledTimes(2);
+  });
+
+  it('tags when the bytes do not sniff as a video', async () => {
+    const upload = vi.fn();
+    const out = await new AgentVideoResolverService(
+      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: PNG_BYTES }]])),
+      blobStore(),
+      telemetry,
+    ).resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ uploadVideo: upload }));
+
+    expect(firstPart(out)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
+    expect(upload).not.toHaveBeenCalled();
+  });
+
+  it('tags a stale reference by its materialization path', async () => {
+    const out = await new AgentVideoResolverService(fileService(new Map()), blobStore(), telemetry).resolve(
+      [videoMessage(buildKimiFileUrl('missing', FALLBACK_PATH))],
+      requester({ uploadVideo: vi.fn() }),
+    );
+
+    expect(firstPart(out)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
+  });
+
+  it('emits an unavailable placeholder when a stale reference has no fallback path', async () => {
+    const out = await new AgentVideoResolverService(fileService(new Map()), blobStore(), telemetry).resolve(
+      [videoMessage(buildKimiFileUrl('missing'))],
+      requester({ uploadVideo: vi.fn() }),
+    );
+
+    expect(firstPart(out)).toEqual({
+      type: 'text',
+      text: '[video omitted: the uploaded file is no longer available]',
+    });
+  });
+
+  it('leaves messages without a kimi-file video untouched', async () => {
+    const resolver = new AgentVideoResolverService(
+      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
+      blobStore(),
+      telemetry,
+    );
+    const messages = [videoMessage('ms://already-uploaded')];
+
+    const out = await resolver.resolve(messages, requester({ uploadVideo: vi.fn() }));
+
+    expect(out).toBe(messages);
+  });
+});
diff --git a/packages/agent-core-v2/test/app/messageLegacy/messageLegacy.test.ts b/packages/agent-core-v2/test/app/messageLegacy/messageLegacy.test.ts
index 1e6655169a..eb102235dd 100644
--- a/packages/agent-core-v2/test/app/messageLegacy/messageLegacy.test.ts
+++ b/packages/agent-core-v2/test/app/messageLegacy/messageLegacy.test.ts
@@ -178,6 +178,54 @@ describe('MessageLegacyService', () => {
     });
   });
 
+  it('projects a kimi-file video reference to a structured file source without leaking the path', async () => {
+    const videoPart = {
+      type: 'video_url',
+      videoUrl: { url: 'kimi-file://file_9?path=%2Fcache%2Fclip.mp4' },
+    } as unknown as ContentPart;
+    const svc = buildService({
+      summary,
+      records: [
+        {
+          type: 'context.append_message',
+          message: { role: 'user', content: [videoPart], toolCalls: [] },
+        },
+      ],
+      contextMessages: [],
+    });
+
+    const page = await svc.list('s1', {});
+
+    expect(page.items[0]?.content[0]).toEqual({
+      type: 'video',
+      source: { kind: 'file', file_id: 'file_9' },
+    });
+  });
+
+  it('projects a provider video url to a structured url source carrying its id', async () => {
+    const videoPart = {
+      type: 'video_url',
+      videoUrl: { url: 'ms://prov-7', id: 'prov-7' },
+    } as unknown as ContentPart;
+    const svc = buildService({
+      summary,
+      records: [
+        {
+          type: 'context.append_message',
+          message: { role: 'user', content: [videoPart], toolCalls: [] },
+        },
+      ],
+      contextMessages: [],
+    });
+
+    const page = await svc.list('s1', {});
+
+    expect(page.items[0]?.content[0]).toEqual({
+      type: 'video',
+      source: { kind: 'url', url: 'ms://prov-7', id: 'prov-7' },
+    });
+  });
+
   it('passes media tool results through as raw content parts instead of flattening', async () => {
     const mediaPart = {
       type: 'image_url',
diff --git a/packages/agent-core/src/agent/tool/index.ts b/packages/agent-core/src/agent/tool/index.ts
index 13a26eeba5..9833707dbc 100644
--- a/packages/agent-core/src/agent/tool/index.ts
+++ b/packages/agent-core/src/agent/tool/index.ts
@@ -776,6 +776,16 @@ export class ToolManager {
     this.initializeBuiltinTools();
   }
 
+  /**
+   * Uploader bound to the agent's current provider, for media that arrives
+   * outside a tool call (e.g. a video attached to a prompt). `undefined`
+   * when no model is bound or the provider has no video upload channel.
+   */
+  videoUploader(): b.VideoUploader | undefined {
+    if (!this.agent.config.hasProvider) return undefined;
+    return this.createVideoUploader(this.agent.config.provider);
+  }
+
   private createVideoUploader(provider: ChatProvider): b.VideoUploader | undefined {
     const uploadVideo = provider.uploadVideo?.bind(provider);
     if (uploadVideo === undefined) return undefined;
@@ -787,10 +797,11 @@ export class ToolManager {
     const baseProps = this.videoUploadTelemetryProps(modelAlias);
     const upload =
       withAuth === undefined
-        ? (input: b.VideoUploadInput) => uploadVideo(input)
-        : (input: b.VideoUploadInput) => withAuth((auth) => uploadVideo(input, { auth }));
+        ? (input: b.VideoUploadInput, signal?: AbortSignal) => uploadVideo(input, { signal })
+        : (input: b.VideoUploadInput, signal?: AbortSignal) =>
+            withAuth((auth) => uploadVideo(input, { auth, signal }));
 
-    return async (input) => {
+    return async (input, options) => {
       const startedAt = Date.now();
       const base = {
         ...baseProps,
@@ -805,7 +816,7 @@ export class ToolManager {
         }
       };
       try {
-        const part = await upload(input);
+        const part = await upload(input, options?.signal);
         track({ ...base, outcome: 'success', duration_ms: Date.now() - startedAt });
         return part;
       } catch (error) {
diff --git a/packages/agent-core/src/agent/turn/index.ts b/packages/agent-core/src/agent/turn/index.ts
index 506f60ae0d..e78da7c6f4 100644
--- a/packages/agent-core/src/agent/turn/index.ts
+++ b/packages/agent-core/src/agent/turn/index.ts
@@ -46,6 +46,7 @@ import {
 } from '../context/projector';
 import { renderUserPromptHookBlockResult, renderUserPromptHookResult } from '../../session/hooks';
 import { canonicalTelemetryArgs, isPlainRecord } from './canonical-args';
+import { degradeUnresolvedVideoToTag, resolvePromptMedia } from './media-resolve';
 import { ToolCallDeduplicator } from './tool-dedup';
 import { budgetToolResultForModel } from './tool-result-budget';
 
@@ -337,7 +338,13 @@ export class TurnFlow {
     const steers = this.steerBuffer;
     if (steers.length === 0) return false;
     for (const steer of steers) {
-      this.agent.context.appendUserMessage(steer.input, steer.origin);
+      // Steer flushes happen at sites that cannot await an upload, so any
+      // prompt-attached local video is degraded to an always-safe `<video
+      // path>` tag here; the model uploads it in-turn via ReadMediaFile.
+      this.agent.context.appendUserMessage(
+        degradeUnresolvedVideoToTag(steer.input),
+        steer.origin,
+      );
     }
     steers.length = 0;
     return true;
@@ -501,7 +508,9 @@ export class TurnFlow {
     this.agent.usage.beginTurn();
     const startedAt = Date.now();
     this.agent.emitEvent({ type: 'turn.started', turnId, origin });
-    this.agent.context.appendUserMessage(input, origin);
+    // The budget-exhausted goal turn does not run the model, so it cannot
+    // await an upload — degrade any local video to the always-safe tag form.
+    this.agent.context.appendUserMessage(degradeUnresolvedVideoToTag(input), origin);
     const ended: TurnEndedEvent = {
       type: 'turn.ended',
       turnId,
@@ -536,7 +545,6 @@ export class TurnFlow {
     this.agent.fullCompaction.resetForTurn();
     this.agent.usage.beginTurn();
     this.agent.emitEvent({ type: 'turn.started', turnId, origin });
-    this.agent.context.appendUserMessage(input, origin);
 
     const startedAt = Date.now();
     let ended: TurnEndedEvent;
@@ -546,7 +554,14 @@ export class TurnFlow {
     // sits just past the turn.ended boundary that consumers watch for.
     let errorEvent: AgentEvent | undefined;
     try {
-      const promptHookEnded = await this.applyUserPromptHook(turnId, input, origin, signal, startedAt);
+      // Resolve any prompt-attached local video (a `file://` video_url) into
+      // its final delivered form — an uploaded `ms://` reference or an
+      // inline/tag fallback — BEFORE it lands in history, so no unresolved
+      // `file://` reference reaches the model or is persisted for resume. Auth
+      // rejections surface as a failed turn via the catch below.
+      const resolvedInput = await resolvePromptMedia(this.agent, input, signal);
+      this.agent.context.appendUserMessage(resolvedInput, origin);
+      const promptHookEnded = await this.applyUserPromptHook(turnId, resolvedInput, origin, signal, startedAt);
       if (promptHookEnded !== undefined) {
         ended = promptHookEnded.event;
         blockedByUserPromptHook = promptHookEnded.blocked;
diff --git a/packages/agent-core/src/agent/turn/media-resolve.ts b/packages/agent-core/src/agent/turn/media-resolve.ts
new file mode 100644
index 0000000000..08d7f4fc1a
--- /dev/null
+++ b/packages/agent-core/src/agent/turn/media-resolve.ts
@@ -0,0 +1,159 @@
+/**
+ * Turn-level prompt media resolution.
+ *
+ * A video attached directly to a prompt rides in as a `video_url` part whose
+ * url is a local `file://` reference (the TUI materializes the paste into a
+ * cache copy and points the part at it). That reference must never reach the
+ * model or the persisted history: the provider would send the `file://` string
+ * verbatim on the wire, and a resumed session would replay it. So the turn
+ * resolves every local `file://` video into its final delivered form — an
+ * uploaded `ms://` reference, or an inline/tag fallback — BEFORE the prompt is
+ * appended to context.
+ *
+ * Two entry points:
+ *   - `resolvePromptMedia` (async): the primary prompt path. Validates and
+ *     uploads through the provider's channel (see `deliverVideoContent`),
+ *     degrading to a `<video path>` tag on validation failure, re-throwing
+ *     auth rejections so the turn fails visibly, and re-throwing the abort
+ *     reason when the turn is cancelled mid-upload so the cancellation ends
+ *     the turn instead of appending a degraded message.
+ *   - `degradeUnresolvedVideoToTag` (sync): the always-safe floor for the few
+ *     append sites that cannot await an upload (steer-buffer flushes, the
+ *     budget-exhausted goal turn). The local video becomes a `<video path>`
+ *     tag the model opens with ReadMediaFile, which uploads it in-turn — the
+ *     same path a pasted video took before inline prompt delivery existed.
+ */
+
+import { fileURLToPath } from 'node:url';
+
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+import type { Agent } from '..';
+import { MEDIA_SNIFF_BYTES, detectFileType } from '../../tools/support/file-type';
+import {
+  deliverVideoContent,
+  inlineVideoSupported,
+  isAuthUploadError,
+} from '../../tools/support/video-delivery';
+import { MAX_MEDIA_BYTES } from '../../tools/builtin/file/read-media';
+import { abortReason } from '../../utils/abort';
+
+/** The local filesystem path behind a prompt-attached `file://` video part. */
+function localVideoUrl(part: ContentPart): string | undefined {
+  return part.type === 'video_url' && part.videoUrl.url.startsWith('file:')
+    ? part.videoUrl.url
+    : undefined;
+}
+
+function escapeAttribute(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+/** A `<video path="…">` tag part the model can open with ReadMediaFile. */
+function videoTag(path: string): ContentPart {
+  return { type: 'text', text: `<video path="${escapeAttribute(path)}"></video>` };
+}
+
+/**
+ * Resolve prompt-attached local videos to their final delivered form. Upload
+ * through the provider channel when the model supports video and the file
+ * validates; otherwise degrade to a `<video path>` tag. Auth rejections from
+ * the upload channel propagate so the turn fails visibly. Returns the input
+ * unchanged when it carries no local video part.
+ */
+export async function resolvePromptMedia(
+  agent: Agent,
+  input: readonly ContentPart[],
+  signal?: AbortSignal,
+): Promise<readonly ContentPart[]> {
+  if (!input.some((part) => localVideoUrl(part) !== undefined)) return input;
+  const resolved: ContentPart[] = [];
+  for (const part of input) {
+    const url = localVideoUrl(part);
+    if (url === undefined) {
+      resolved.push(part);
+      continue;
+    }
+    resolved.push(await resolveOneVideo(agent, url, signal));
+  }
+  return resolved;
+}
+
+async function resolveOneVideo(
+  agent: Agent,
+  fileUrl: string,
+  signal?: AbortSignal,
+): Promise<ContentPart> {
+  let path: string;
+  try {
+    path = fileURLToPath(fileUrl);
+  } catch {
+    // A malformed file URL cannot name a readable file — degrade to a tag
+    // rather than let the raw reference reach the provider.
+    return videoTag(fileUrl);
+  }
+  try {
+    // Validation ladder — any failure degrades to a tag (always safe): the
+    // model reads the file with ReadMediaFile, which re-validates and uploads.
+    if (path.trim().length === 0) return videoTag(path);
+    if (!agent.config.modelCapabilities.video_in) return videoTag(path);
+    const header = await agent.kaos.readBytes(path, MEDIA_SNIFF_BYTES);
+    const fileType = detectFileType(path, header, 'media');
+    if (fileType.kind !== 'video') return videoTag(path);
+    const stat = await agent.kaos.stat(path);
+    if (stat.stSize === 0) return videoTag(path);
+    if (stat.stSize > MAX_MEDIA_BYTES) return videoTag(path);
+
+    const data = await agent.kaos.readBytes(path);
+    const uploader = agent.tools.videoUploader();
+    // No upload channel and a wire that drops inline video (OpenAI family):
+    // the tag is the only form that actually reaches the model — an inline
+    // part would persist ~4/3× the file size in history just to be degraded
+    // to a placeholder on every request.
+    if (
+      uploader === undefined &&
+      agent.config.hasProvider &&
+      !inlineVideoSupported(agent.config.provider.name)
+    ) {
+      return videoTag(path);
+    }
+    return await deliverVideoContent(
+      { data, mimeType: fileType.mimeType, filename: path.split(/[\\/]/).at(-1) },
+      uploader,
+      signal,
+    );
+  } catch (error) {
+    // A cancelled turn surfaces as its abort reason — whatever error the
+    // interrupted read/upload happened to produce, the user's cancellation is
+    // the real outcome, not a delivery failure to degrade around. Auth
+    // rejections must also surface (credential refresh + clear error); any
+    // other read/upload failure degrades to the always-safe tag form.
+    if (signal?.aborted) throw abortReason(signal);
+    if (isAuthUploadError(error)) throw error;
+    return videoTag(path);
+  }
+}
+
+/**
+ * Synchronously replace every prompt-attached local `file://` video part with
+ * a `<video path>` tag. The always-safe floor for append sites that cannot
+ * await an upload. Returns the input unchanged when it carries no local video.
+ */
+export function degradeUnresolvedVideoToTag(
+  input: readonly ContentPart[],
+): readonly ContentPart[] {
+  if (!input.some((part) => localVideoUrl(part) !== undefined)) return input;
+  return input.map((part) => {
+    const url = localVideoUrl(part);
+    if (url === undefined) return part;
+    try {
+      return videoTag(fileURLToPath(url));
+    } catch {
+      return videoTag(url);
+    }
+  });
+}
diff --git a/packages/agent-core/src/tools/builtin/file/read-media.ts b/packages/agent-core/src/tools/builtin/file/read-media.ts
index 0f46154f1f..fb2724b469 100644
--- a/packages/agent-core/src/tools/builtin/file/read-media.ts
+++ b/packages/agent-core/src/tools/builtin/file/read-media.ts
@@ -28,7 +28,6 @@ import type { Kaos } from '@moonshot-ai/kaos';
 import type {
   ContentPart,
   ModelCapability,
-  VideoURLPart,
   VideoUploadInput as ProviderVideoUploadInput,
 } from '@moonshot-ai/kosong';
 import { z } from 'zod';
@@ -40,6 +39,7 @@ import type { TelemetryClient } from '../../../telemetry';
 import { renderPrompt } from '../../../utils/render-prompt';
 import { resolvePathAccessPath } from '../../policies/path-access';
 import { MEDIA_SNIFF_BYTES, detectFileType, sniffImageDimensions } from '../../support/file-type';
+import { deliverVideoContent, type VideoUploader } from '../../support/video-delivery';
 import {
   IMAGE_BYTE_BUDGET,
   MAX_IMAGE_DECODE_BYTES,
@@ -62,7 +62,7 @@ import readMediaDescriptionHead from './read-media.md?raw';
 // ── Constants ────────────────────────────────────────────────────────
 
 const MAX_MEDIA_MEGABYTES = 100;
-const MAX_MEDIA_BYTES = MAX_MEDIA_MEGABYTES * 1024 * 1024;
+export const MAX_MEDIA_BYTES = MAX_MEDIA_MEGABYTES * 1024 * 1024;
 
 function buildImageDeliveryLimitError(input: {
   readonly finalBytes: number;
@@ -99,7 +99,7 @@ function buildFullResolutionLimitError(path: string, finalBytes: number): string
 
 export type VideoUploadInput = ProviderVideoUploadInput;
 
-export type VideoUploader = (input: VideoUploadInput) => Promise<VideoURLPart>;
+export type { VideoUploader };
 
 // ── Input schema ─────────────────────────────────────────────────────
 
@@ -277,6 +277,26 @@ export class ReadMediaFileTool implements BuiltinTool<ReadMediaFileInput> {
     this.imageLimits = imageLimits ?? new ImageLimits();
   }
 
+  /**
+   * Deliver a video through the provider's upload channel when available,
+   * falling back to an inline base64 part when the channel is missing or
+   * broken (e.g. the provider has no files endpoint) — a failed upload must
+   * not turn the whole read into an error. Auth rejections (401/403) are
+   * the exception: they must surface, because they drive credential
+   * refresh and a clear auth error instead of masking a bad token behind
+   * an inline payload the next request will also reject.
+   */
+  private videoContentPart(
+    data: Buffer,
+    mimeType: string,
+    safePath: string,
+  ): Promise<ContentPart> {
+    return deliverVideoContent(
+      { data, mimeType, filename: safePath.split(/[\\/]/).at(-1) },
+      this.videoUploader,
+    );
+  }
+
   resolveExecution(args: ReadMediaFileInput): ToolExecution {
     const path = resolvePathAccessPath(args.path, {
       kaos: this.kaos,
@@ -534,18 +554,8 @@ export class ReadMediaFileTool implements BuiltinTool<ReadMediaFileInput> {
             dimensions = { width: compressed.originalWidth, height: compressed.originalHeight };
           }
         }
-      } else if (this.videoUploader !== undefined) {
-        mediaPart = await this.videoUploader({
-          data,
-          mimeType: fileType.mimeType,
-          filename: safePath.split(/[\\/]/).at(-1),
-        });
       } else {
-        const base64 = data.toString('base64');
-        mediaPart = {
-          type: 'video_url',
-          videoUrl: { url: `data:${fileType.mimeType};base64,${base64}` },
-        };
+        mediaPart = await this.videoContentPart(data, fileType.mimeType, safePath);
       }
 
       const tag = fileType.kind === 'image' ? 'image' : 'video';
diff --git a/packages/agent-core/src/tools/support/video-delivery.ts b/packages/agent-core/src/tools/support/video-delivery.ts
new file mode 100644
index 0000000000..aec6ac364e
--- /dev/null
+++ b/packages/agent-core/src/tools/support/video-delivery.ts
@@ -0,0 +1,89 @@
+/**
+ * Shared video delivery ladder.
+ *
+ * A local video becomes a model-visible content part through one channel:
+ * upload it via the provider's video upload channel (the tiny `ms://<id>`
+ * reference), and only fall back to an inline base64 `data:` part when the
+ * channel is missing or the upload fails for a non-auth reason. Two failures
+ * are the exception and must surface instead of being masked behind an inline
+ * payload: auth rejections (401/403), which drive credential refresh and a
+ * clear auth error, and a cancelled delivery signal — the caller is tearing
+ * the turn down, so the interruption propagates as the signal's abort reason
+ * rather than silently delivering a degraded part.
+ *
+ * Both ReadMediaFile (videos the model reads itself) and the turn-level
+ * prompt-media resolver (videos attached directly to a prompt) share this
+ * ladder so their delivery and fallback semantics stay identical.
+ */
+
+import type { ContentPart, VideoUploadInput, VideoURLPart } from '@moonshot-ai/kosong';
+
+import { ErrorCodes } from '../../errors';
+import { abortReason } from '../../utils/abort';
+
+/** Uploads a local video and returns the provider-issued `video_url` part. */
+export type VideoUploader = (
+  input: VideoUploadInput,
+  options?: { signal?: AbortSignal },
+) => Promise<VideoURLPart>;
+
+/**
+ * Auth rejections from the upload channel that must surface (they drive
+ * credential refresh and a clear auth error). The auth layer wraps provider
+ * 401/403s as `provider.auth_error`; a raw status-coded error is matched
+ * directly.
+ */
+export function isAuthUploadError(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  if ((error as { code?: unknown }).code === ErrorCodes.PROVIDER_AUTH_ERROR) return true;
+  const statusCode = (error as { statusCode?: unknown }).statusCode;
+  return statusCode === 401 || statusCode === 403;
+}
+
+/**
+ * Whether the provider's wire format can carry an inline `data:` video part.
+ * The OpenAI family cannot: chat completions rejects the part outright and
+ * the Responses adapter degrades it to an omitted-video placeholder, so an
+ * inline fallback there only bloats history with bytes the model never sees.
+ */
+export function inlineVideoSupported(providerName: string): boolean {
+  return providerName !== 'openai' && providerName !== 'openai-responses';
+}
+
+/**
+ * Deliver a video through the provider's upload channel when available,
+ * falling back to an inline base64 part when the channel is missing or the
+ * upload fails for a non-auth reason — a failed upload must not turn the whole
+ * delivery into an error. Auth rejections (401/403) are re-thrown so the
+ * caller can surface them, and a cancelled `signal` re-throws its abort
+ * reason so cancellation ends the delivery instead of degrading it.
+ */
+export async function deliverVideoContent(
+  input: VideoUploadInput,
+  uploader: VideoUploader | undefined,
+  signal?: AbortSignal,
+): Promise<ContentPart> {
+  if (uploader !== undefined) {
+    try {
+      // Call with a single argument when there is no signal to thread, so
+      // callers that never cancel (ReadMediaFile) invoke the channel exactly
+      // as before signal support existed.
+      return await (signal === undefined ? uploader(input) : uploader(input, { signal }));
+    } catch (error) {
+      // The signal check (not the error's shape) decides cancellation: abort
+      // rejections vary by provider, but our own aborted signal is definitive.
+      if (signal?.aborted) throw abortReason(signal);
+      if (isAuthUploadError(error)) throw error;
+      // Fall through to the inline form.
+    }
+  }
+  // Cancellation must also beat the no-uploader inline path: encoding up to
+  // 100MB after the user aborted only produces a part the caller would then
+  // persist against their intent.
+  if (signal?.aborted) throw abortReason(signal);
+  const base64 = Buffer.from(input.data).toString('base64');
+  return {
+    type: 'video_url',
+    videoUrl: { url: `data:${input.mimeType};base64,${base64}` },
+  };
+}
diff --git a/packages/agent-core/src/utils/abort.ts b/packages/agent-core/src/utils/abort.ts
index d452f0079e..2a7bdcf413 100644
--- a/packages/agent-core/src/utils/abort.ts
+++ b/packages/agent-core/src/utils/abort.ts
@@ -59,7 +59,7 @@ export function linkAbortSignal(source: AbortSignal, target: AbortController): (
   };
 }
 
-function abortReason(signal: AbortSignal): Error {
+export function abortReason(signal: AbortSignal): Error {
   if (signal.reason instanceof Error && !isDefaultAbortReason(signal.reason)) {
     return signal.reason;
   }
diff --git a/packages/agent-core/test/agent/basic.test.ts b/packages/agent-core/test/agent/basic.test.ts
index dd0fc16376..1df4648ecf 100644
--- a/packages/agent-core/test/agent/basic.test.ts
+++ b/packages/agent-core/test/agent/basic.test.ts
@@ -1,5 +1,11 @@
-import type { ToolCall } from '@moonshot-ai/kosong';
-import { expect, it } from 'vitest';
+import type { ContentPart, ToolCall } from '@moonshot-ai/kosong';
+import { createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { mkdtempSync, truncateSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { describe, expect, it, vi } from 'vitest';
 
 import { FLAG_DEFINITIONS, FlagResolver } from '../../src/flags';
 import { createCommandKaos, testAgent } from './harness/agent';
@@ -151,3 +157,352 @@ it('runs an agent turn through builtin tool approval and execution', async () =>
   `);
   await ctx.expectResumeMatches();
 });
+
+const VIDEO_CAPS = {
+  image_in: true,
+  video_in: true,
+  audio_in: false,
+  thinking: false,
+  tool_use: true,
+  max_context_tokens: 1000000,
+} as const;
+
+describe('prompt-attached video resolution', () => {
+  // Minimal ISO-BMFF header: a 24-byte ftyp box with the `isom` brand, which
+  // is all the media sniffer needs to classify the file as video/mp4.
+  const FTYP_MP4 = Buffer.from([
+    0x00, 0x00, 0x00, 0x18, 0x66, 0x74, 0x79, 0x70, 0x69, 0x73, 0x6f, 0x6d, 0x00, 0x00, 0x02,
+    0x00, 0x69, 0x73, 0x6f, 0x6d, 0x69, 0x73, 0x6f, 0x32,
+  ]);
+
+  function tempVideo(name = 'clip.mp4', bytes: Buffer = FTYP_MP4): string {
+    const dir = mkdtempSync(join(tmpdir(), 'agent-prompt-video-'));
+    const path = join(dir, name);
+    writeFileSync(path, bytes);
+    return path;
+  }
+
+  function fileUrl(path: string): string {
+    return pathToFileURL(path).href;
+  }
+
+  function firstUserContent(ctx: ReturnType<typeof testAgent>): ContentPart[] {
+    return ctx.agent.context.messages.find((m) => m.role === 'user')?.content ?? [];
+  }
+
+  interface StubFilesServer {
+    url: string;
+    requests: number;
+    close: () => Promise<void>;
+  }
+
+  // Stubs the Moonshot files endpoint. `status` drives the ladder: 200 issues a
+  // reference, 401 exercises the auth-rejection path, any other status is a
+  // non-auth upload failure.
+  async function stubFilesServer(status = 200): Promise<StubFilesServer> {
+    const state = { requests: 0 };
+    const server = createServer((req, res) => {
+      if (req.method === 'POST' && req.url === '/files') {
+        req.resume();
+        req.on('end', () => {
+          state.requests += 1;
+          if (status === 200) {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(
+              JSON.stringify({
+                id: 'stub-video-file',
+                object: 'file',
+                bytes: FTYP_MP4.length,
+                created_at: 0,
+                filename: 'clip.mp4',
+                purpose: 'video',
+              }),
+            );
+            return;
+          }
+          res.writeHead(status, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: { message: 'stub upload failure' } }));
+        });
+        return;
+      }
+      res.writeHead(404);
+      res.end();
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address() as AddressInfo;
+    return {
+      url: `http://127.0.0.1:${String(port)}`,
+      get requests() {
+        return state.requests;
+      },
+      close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+    };
+  }
+
+  function kimiProvider(baseUrl: string) {
+    return { type: 'kimi', apiKey: 'test-key', model: 'mock-model', baseUrl } as const;
+  }
+
+  it('uploads a local file:// video and sends the issued ms:// reference to the model', async () => {
+    const stub = await stubFilesServer();
+    try {
+      const ctx = testAgent();
+      ctx.configure({ provider: kimiProvider(stub.url), modelCapabilities: VIDEO_CAPS });
+      ctx.mockNextResponse({ type: 'text', text: 'ok' });
+
+      await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(tempVideo()) } }] });
+      await ctx.untilTurnEnd();
+
+      expect(firstUserContent(ctx)).toContainEqual({
+        type: 'video_url',
+        videoUrl: { url: 'ms://stub-video-file', id: 'stub-video-file' },
+      });
+      expect(stub.requests).toBe(1);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  it('ends the turn as cancelled when the user aborts mid-upload, appending nothing', async () => {
+    // A /files stub that never responds: the upload only settles when the
+    // turn's abort signal tears the in-flight request down, so the rejection
+    // reaching the resolver is whatever shape the HTTP client aborts with —
+    // the aborted signal alone must classify it as a cancellation.
+    let requestArrived!: () => void;
+    const arrived = new Promise<void>((resolve) => {
+      requestArrived = resolve;
+    });
+    const server = createServer((req) => {
+      req.resume();
+      requestArrived();
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address() as AddressInfo;
+    try {
+      const ctx = testAgent();
+      ctx.configure({
+        provider: kimiProvider(`http://127.0.0.1:${String(port)}`),
+        modelCapabilities: VIDEO_CAPS,
+      });
+
+      await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(tempVideo()) } }] });
+      await arrived;
+      await ctx.rpc.cancel({ turnId: 0 });
+      const events = await ctx.untilTurnEnd();
+
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          event: 'turn.ended',
+          args: expect.objectContaining({ reason: 'cancelled' }),
+        }),
+      );
+      // The cancelled prompt is not delivered at all: no user message enters
+      // history, and in particular no inline-base64 degraded copy of it.
+      expect(ctx.agent.context.data().history).toEqual([]);
+    } finally {
+      server.closeAllConnections();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it('ends the turn as cancelled when the user aborts before the inline fallback', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      // Anthropic: no upload channel, so resolution heads for the inline
+      // fallback — the abort must beat the base64 encode.
+      provider: { type: 'anthropic', apiKey: 'test-key', model: 'mock-model' },
+      modelCapabilities: VIDEO_CAPS,
+    });
+
+    const path = tempVideo();
+    const realReadBytes = ctx.agent.kaos.readBytes.bind(ctx.agent.kaos);
+    vi.spyOn(ctx.agent.kaos, 'readBytes').mockImplementation(async (p, length) => {
+      // The uncapped full-content read is the window the user cancels in.
+      if (length === undefined) await ctx.rpc.cancel({ turnId: 0 });
+      return realReadBytes(p, length);
+    });
+
+    await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(path) } }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({ reason: 'cancelled' }),
+      }),
+    );
+    expect(ctx.agent.context.data().history).toEqual([]);
+  });
+
+  it('degrades to a <video path> tag when the model lacks video_in (no upload)', async () => {
+    const stub = await stubFilesServer();
+    try {
+      const ctx = testAgent();
+      ctx.configure({
+        provider: kimiProvider(stub.url),
+        modelCapabilities: { ...VIDEO_CAPS, video_in: false },
+      });
+      ctx.mockNextResponse({ type: 'text', text: 'ok' });
+
+      const path = tempVideo();
+      await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(path) } }] });
+      await ctx.untilTurnEnd();
+
+      const text = firstUserContent(ctx)
+        .map((p) => (p.type === 'text' ? p.text : ''))
+        .join('');
+      expect(text).toContain(`<video path="${path}">`);
+      expect(firstUserContent(ctx).some((p) => p.type === 'video_url')).toBe(false);
+      expect(stub.requests).toBe(0);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  it('falls back to an inline base64 part when the provider has no upload channel', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      // Anthropic: no upload channel, but the wire carries inline data: video.
+      provider: { type: 'anthropic', apiKey: 'test-key', model: 'mock-model' },
+      modelCapabilities: VIDEO_CAPS,
+    });
+    ctx.mockNextResponse({ type: 'text', text: 'ok' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(tempVideo()) } }] });
+    await ctx.untilTurnEnd();
+
+    const part = firstUserContent(ctx).find((p) => p.type === 'video_url');
+    expect(part?.type === 'video_url' && part.videoUrl.url).toMatch(/^data:video\/mp4;base64,/);
+  });
+
+  it.each(['openai', 'openai_responses'] as const)(
+    'degrades to a <video path> tag for a no-upload %s provider whose wire drops inline video',
+    async (type) => {
+      const ctx = testAgent();
+      ctx.configure({
+        provider: { type, apiKey: 'test-key', model: 'mock-model' },
+        modelCapabilities: VIDEO_CAPS,
+      });
+      ctx.mockNextResponse({ type: 'text', text: 'ok' });
+
+      const path = tempVideo();
+      await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(path) } }] });
+      await ctx.untilTurnEnd();
+
+      const text = firstUserContent(ctx)
+        .map((p) => (p.type === 'text' ? p.text : ''))
+        .join('');
+      expect(text).toContain(`<video path="${path}">`);
+      expect(firstUserContent(ctx).some((p) => p.type === 'video_url')).toBe(false);
+    },
+  );
+
+  it('falls back to an inline base64 part on a non-auth upload failure', async () => {
+    const stub = await stubFilesServer(400);
+    try {
+      const ctx = testAgent();
+      ctx.configure({ provider: kimiProvider(stub.url), modelCapabilities: VIDEO_CAPS });
+      ctx.mockNextResponse({ type: 'text', text: 'ok' });
+
+      await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(tempVideo()) } }] });
+      await ctx.untilTurnEnd();
+
+      const part = firstUserContent(ctx).find((p) => p.type === 'video_url');
+      expect(part?.type === 'video_url' && part.videoUrl.url).toMatch(/^data:video\/mp4;base64,/);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  it('fails the turn on an auth (401) upload rejection without poisoning history', async () => {
+    const stub = await stubFilesServer(401);
+    try {
+      const ctx = testAgent();
+      ctx.configure({ provider: kimiProvider(stub.url), modelCapabilities: VIDEO_CAPS });
+
+      await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(tempVideo()) } }] });
+      const events = await ctx.untilTurnEnd();
+
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          event: 'turn.ended',
+          args: expect.objectContaining({ reason: 'failed' }),
+        }),
+      );
+      // The unresolved video is never appended to history.
+      expect(ctx.agent.context.messages.some((m) => m.role === 'user')).toBe(false);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  it('degrades a non-video file to a tag (magic bytes win, no upload)', async () => {
+    const stub = await stubFilesServer();
+    try {
+      const ctx = testAgent();
+      ctx.configure({ provider: kimiProvider(stub.url), modelCapabilities: VIDEO_CAPS });
+      ctx.mockNextResponse({ type: 'text', text: 'ok' });
+
+      const path = tempVideo('notes.txt', Buffer.from('definitely not a video'));
+      await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(path) } }] });
+      await ctx.untilTurnEnd();
+
+      expect(firstUserContent(ctx).some((p) => p.type === 'video_url')).toBe(false);
+      expect(stub.requests).toBe(0);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  it('degrades an oversize video (>100MB) to a tag (no upload)', async () => {
+    const stub = await stubFilesServer();
+    try {
+      const ctx = testAgent();
+      ctx.configure({ provider: kimiProvider(stub.url), modelCapabilities: VIDEO_CAPS });
+      ctx.mockNextResponse({ type: 'text', text: 'ok' });
+
+      const path = tempVideo();
+      // Sparse extend: the ftyp header stays so it sniffs as video, the size
+      // crosses the cap.
+      truncateSync(path, 100 * 1024 * 1024 + 1);
+      await ctx.rpc.prompt({ input: [{ type: 'video_url', videoUrl: { url: fileUrl(path) } }] });
+      await ctx.untilTurnEnd();
+
+      expect(firstUserContent(ctx).some((p) => p.type === 'video_url')).toBe(false);
+      expect(stub.requests).toBe(0);
+    } finally {
+      await stub.close();
+    }
+  }, 30000);
+
+  it('resolves a video attached to a steer message', async () => {
+    const stub = await stubFilesServer();
+    try {
+      const ctx = testAgent();
+      ctx.configure({ provider: kimiProvider(stub.url), modelCapabilities: VIDEO_CAPS });
+      // Two model steps: the first lets the steer buffer while the turn runs,
+      // the second reacts to the flushed steer.
+      ctx.mockNextResponse({ type: 'text', text: 'first' });
+      ctx.mockNextResponse({ type: 'text', text: 'second' });
+
+      await ctx.rpc.prompt({ input: [{ type: 'text', text: 'start' }] });
+      const path = tempVideo();
+      ctx.agent.turn.steer([{ type: 'video_url', videoUrl: { url: fileUrl(path) } }]);
+      await ctx.untilTurnEnd();
+
+      // The steer flush cannot await an upload, so the local video degrades to
+      // an always-safe tag — no unresolved file:// reference reaches history.
+      const steered = ctx.agent.context.messages.filter((m) => m.role === 'user');
+      const hasFileUrl = steered.some((m) =>
+        m.content.some((p) => p.type === 'video_url' && p.videoUrl.url.startsWith('file:')),
+      );
+      expect(hasFileUrl).toBe(false);
+      const anyTag = steered.some((m) =>
+        m.content.some((p) => p.type === 'text' && p.text.includes(`<video path="${path}">`)),
+      );
+      expect(anyTag).toBe(true);
+    } finally {
+      await stub.close();
+    }
+  });
+});
diff --git a/packages/agent-core/test/tools/read-media.test.ts b/packages/agent-core/test/tools/read-media.test.ts
index 67a0aad985..679aee2b37 100644
--- a/packages/agent-core/test/tools/read-media.test.ts
+++ b/packages/agent-core/test/tools/read-media.test.ts
@@ -419,6 +419,65 @@ describe('ReadMediaFileTool', () => {
     });
   });
 
+  it('falls back to an inline base64 video part when the upload fails', async () => {
+    const videoUploader = vi.fn().mockRejectedValue(new Error('404 route not found'));
+    const tool = new ReadMediaFileTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue({
+          ...DEFAULT_STAT,
+          stSize: MP4_HEADER.length,
+        }),
+        readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(MP4_HEADER),
+      }),
+      PERMISSIVE_WORKSPACE,
+      capabilities(),
+      videoUploader,
+    );
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c4b',
+      args: { path: '/workspace/sample.mp4' },
+      signal,
+    });
+
+    expect(result.isError).not.toBe(true);
+    const parts = outputParts(result);
+    expect(parts[1]).toEqual({
+      type: 'video_url',
+      videoUrl: { url: `data:video/mp4;base64,${MP4_HEADER.toString('base64')}` },
+    });
+  });
+
+  it('surfaces auth rejections from the upload channel instead of falling back', async () => {
+    const videoUploader = vi
+      .fn()
+      .mockRejectedValue(Object.assign(new Error('401 Unauthorized'), { statusCode: 401 }));
+    const tool = new ReadMediaFileTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue({
+          ...DEFAULT_STAT,
+          stSize: MP4_HEADER.length,
+        }),
+        readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(MP4_HEADER),
+      }),
+      PERMISSIVE_WORKSPACE,
+      capabilities(),
+      videoUploader,
+    );
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c4c',
+      args: { path: '/workspace/sample.mp4' },
+      signal,
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.output).toContain('401 Unauthorized');
+    expect(result.output).not.toContain('base64');
+  });
+
   it('rejects text files with a Read hint', async () => {
     const text = Buffer.from('hello');
     const tool = makeReadMediaTool({
diff --git a/packages/kap-server/src/routes/prompts.ts b/packages/kap-server/src/routes/prompts.ts
index 1b5fa9b330..2520ad63ac 100644
--- a/packages/kap-server/src/routes/prompts.ts
+++ b/packages/kap-server/src/routes/prompts.ts
@@ -22,6 +22,8 @@ import {
   IEventService,
   IFileService,
   ISessionMetadata,
+  buildKimiFileUrl,
+  parseKimiFileUrl,
   promptMetadataTextFromContentParts,
   ProfileError,
   type ContentPart,
@@ -179,6 +181,24 @@ async function applyProfileSelection(
   return true;
 }
 
+/**
+ * Fail fast on stale or mis-kinded file references before anything
+ * session-scoped happens: a bad `file_id` (unknown, or a real file used with
+ * the wrong media kind, e.g. a PDF submitted as a video) must reject the
+ * request without creating the prompt agent and without touching the
+ * session's model/thinking/permission.
+ */
+async function assertPromptFileRefs(body: PromptSubmission, store: IFileService): Promise<void> {
+  for (const part of body.content) {
+    if (part.type === 'file') {
+      await store.get(part.file_id);
+    } else if ((part.type === 'image' || part.type === 'video') && part.source.kind === 'file') {
+      const file = await store.get(part.source.file_id);
+      assertMediaFile(file, part.type);
+    }
+  }
+}
+
 export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
   const listRoute = defineRoute(
     {
@@ -217,7 +237,6 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
         [ErrorCode.AUTH_TOKEN_UNAUTHORIZED]: { detailsSchema: authProviderDetailsSchema },
         [ErrorCode.AUTH_MODEL_NOT_RESOLVED]: { detailsSchema: authModelDetailsSchema },
         [ErrorCode.SESSION_NOT_FOUND]: {},
-        [ErrorCode.SESSION_BUSY]: {},
         [ErrorCode.PROMPT_ALREADY_COMPLETED]: { dataSchema: z.object({ aborted: z.literal(false) }) },
       },
       description: 'Submit a prompt to a session',
@@ -225,14 +244,28 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
       operationId: 'submitPrompt',
     },
     async (req, reply) => {
+      const { session_id } = req.params;
       try {
-        const { session_id } = req.params;
+        // Fail fast on stale file references before anything is resolved or
+        // mutated: a bad `file_id` must not create the agent, register `main`
+        // in session metadata, or touch the session's controls.
+        await assertPromptFileRefs(req.body, core.accessor.get(IFileService));
+        const resolved = await resolvePrompt(core, session_id, req.body.agent_id);
+        await resolved.auth.ensureReady();
+
+        // Media resolution runs BEFORE any control mutation, so a failed
+        // submission leaves the session's controls untouched. Prompt videos
+        // are materialized to a local copy and carried into context as an
+        // internal `kimi-file://` reference; the engine resolves them to a
+        // provider form (upload / inline / `<video path>` tag) at request
+        // time, so the edge no longer uploads.
+        const telemetry = core.accessor.get(ITelemetryService).withContext({ sessionId: session_id });
         const resolvedBody = await resolvePromptMediaFiles(
           req.body,
           core.accessor.get(IFileService),
           core.accessor.get(IBootstrapService).cacheDir,
           {
-            telemetry: core.accessor.get(ITelemetryService).withContext({ sessionId: session_id }),
+            telemetry,
             resolveOriginalsDir: async () => {
               const session = await core.accessor.get(ISessionLifecycleService).resume(session_id);
               if (session === undefined) return undefined;
@@ -245,28 +278,27 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
             },
           },
         );
-        const resolved = await resolvePrompt(core, session_id, resolvedBody.agent_id);
-        await resolved.auth.ensureReady();
-        const session = await resolveSession(core, session_id);
+
+        // Media prepared successfully — only now do the overrides bind.
         let thinkingConsumed = false;
-        if (resolvedBody.profile !== undefined) {
+        if (req.body.profile !== undefined) {
           thinkingConsumed =
             (await applyProfileSelection(
               resolved.profile,
-              resolvedBody.profile,
-              resolvedBody.model,
-              resolvedBody.thinking,
-            )) && resolvedBody.thinking !== undefined;
+              req.body.profile,
+              req.body.model,
+              req.body.thinking,
+            )) && req.body.thinking !== undefined;
         }
-        if (resolvedBody.model !== undefined) await resolved.profile.setModel(resolvedBody.model);
-        if (resolvedBody.thinking !== undefined && !thinkingConsumed)
-          resolved.profile.setThinking(resolvedBody.thinking);
-        if (resolvedBody.permission_mode !== undefined) resolved.permissionMode.setMode(resolvedBody.permission_mode);
-        if (resolvedBody.disabled_tools !== undefined) {
+        if (req.body.model !== undefined) await resolved.profile.setModel(req.body.model);
+        if (req.body.thinking !== undefined && !thinkingConsumed)
+          resolved.profile.setThinking(req.body.thinking);
+        if (req.body.permission_mode !== undefined) resolved.permissionMode.setMode(req.body.permission_mode);
+        if (req.body.disabled_tools !== undefined) {
           // A session denylist before bind throws `profile.not_bound` — map it
           // onto 40001 like the profile-selection errors above.
           try {
-            await resolved.toolPolicy.setSessionDisabledTools(resolvedBody.disabled_tools);
+            await resolved.toolPolicy.setSessionDisabledTools(req.body.disabled_tools);
           } catch (error) {
             if (error instanceof ProfileError) {
               throw new Error2(ErrorCodes.REQUEST_INVALID, error.message);
@@ -275,6 +307,7 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
           }
         }
         const parts = contentToCoreParts(resolvedBody.content);
+        const session = await resolveSession(core, session_id);
         await applyPromptMetadataUpdate({
           metadata: session.accessor.get(ISessionMetadata),
           eventService: core.accessor.get(IEventService),
@@ -399,12 +432,20 @@ function corePartsToProtocol(content: readonly ContentPart[]): PromptSubmission[
     else if (part.type === 'image_url') {
       const match = /^data:([^;]+);base64,(.*)$/.exec(part.imageUrl.url);
       parts.push(match === null
-        ? { type: 'image', source: { kind: 'url', url: part.imageUrl.url } }
+        ? { type: 'image', source: { kind: 'url', url: part.imageUrl.url, id: part.imageUrl.id } }
         : { type: 'image', source: { kind: 'base64', media_type: match[1]!, data: match[2]! } });
     } else if (part.type === 'video_url') {
+      // An internal `kimi-file://<id>?path=…` reference projects back to the
+      // daemon upload it came from — the materialization path never leaks to
+      // the client.
+      const kimiFile = parseKimiFileUrl(part.videoUrl.url);
+      if (kimiFile !== undefined) {
+        parts.push({ type: 'video', source: { kind: 'file', file_id: kimiFile.fileId } });
+        continue;
+      }
       const match = /^data:([^;]+);base64,(.*)$/.exec(part.videoUrl.url);
       parts.push(match === null
-        ? { type: 'video', source: { kind: 'url', url: part.videoUrl.url } }
+        ? { type: 'video', source: { kind: 'url', url: part.videoUrl.url, id: part.videoUrl.id } }
         : { type: 'video', source: { kind: 'base64', media_type: match[1]!, data: match[2]! } });
     }
   }
@@ -415,9 +456,9 @@ function contentToCoreParts(content: PromptSubmission['content']): ContentPart[]
   const parts: ContentPart[] = [];
   for (const part of content) {
     if (part.type === 'text') parts.push({ type: 'text', text: part.text });
-    else if (part.type === 'image' && part.source.kind === 'url') parts.push({ type: 'image_url', imageUrl: { url: part.source.url } });
+    else if (part.type === 'image' && part.source.kind === 'url') parts.push({ type: 'image_url', imageUrl: { url: part.source.url, id: part.source.id } });
     else if (part.type === 'image' && part.source.kind === 'base64') parts.push({ type: 'image_url', imageUrl: { url: `data:${part.source.media_type};base64,${part.source.data}` } });
-    else if (part.type === 'video' && part.source.kind === 'url') parts.push({ type: 'video_url', videoUrl: { url: part.source.url } });
+    else if (part.type === 'video' && part.source.kind === 'url') parts.push({ type: 'video_url', videoUrl: { url: part.source.url, id: part.source.id } });
     else if (part.type === 'video' && part.source.kind === 'base64') parts.push({ type: 'video_url', videoUrl: { url: `data:${part.source.media_type};base64,${part.source.data}` } });
   }
   return parts;
@@ -649,8 +690,16 @@ async function resolvePromptMediaFiles(
       continue;
     }
 
+    // Uploaded video: materialize a local copy the model can open as a
+    // fallback, and carry the upload into context as an internal
+    // `kimi-file://<id>?path=<materialized path>` reference. The engine
+    // resolves it to a provider form (upload / inline / `<video path>` tag) at
+    // request time, so the edge never uploads and never blocks on the provider.
     const cachePath = await materializeVideoToCache(file, cacheDir);
-    content.push({ type: 'text', text: `<video path="${escapeAttribute(cachePath)}"></video>` });
+    content.push({
+      type: 'video',
+      source: { kind: 'url', url: buildKimiFileUrl(file.meta.id, cachePath) },
+    });
     changed = true;
   }
   return changed ? { ...body, content } : body;
@@ -748,14 +797,6 @@ function assertMediaFile(file: GetResult, expected: 'image' | 'video'): void {
   );
 }
 
-function escapeAttribute(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('"', '&quot;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;');
-}
-
 function sendMappedError(
   reply: { send(payload: unknown): unknown },
   req: { id: string },
diff --git a/packages/kap-server/test/prompts.test.ts b/packages/kap-server/test/prompts.test.ts
index 14603c63d9..0db4a13480 100644
--- a/packages/kap-server/test/prompts.test.ts
+++ b/packages/kap-server/test/prompts.test.ts
@@ -213,7 +213,50 @@ describe('server-v2 /api/v1 prompts', () => {
     expect(Array.isArray(list.body.data.queued)).toBe(true);
   });
 
-  it('materializes uploaded video prompts into cache path tags', async () => {
+  it('rejects a stale file reference without creating the agent or mutating the model', async () => {
+    const id = await createSession(home as string);
+    const session = server!.core.accessor.get(ISessionLifecycleService).get(id);
+
+    const { body } = await call<null>('POST', `/api/v1/sessions/${id}/prompts`, {
+      model: 'stub',
+      content: [
+        { type: 'text', text: 'look' },
+        { type: 'video', source: { kind: 'file', file_id: 'f_does_not_exist' } },
+      ],
+    });
+    expect(body.code).toBe(40407);
+
+    // The failed request must not have materialized the main agent either.
+    expect(session!.accessor.get(IAgentLifecycleService).get('main')).toBeUndefined();
+  });
+
+  it('rejects a mis-kinded file reference without creating the agent', async () => {
+    const id = await createSession(home as string);
+    const session = server!.core.accessor.get(ISessionLifecycleService).get(id);
+
+    // A real upload, but referenced with the wrong media kind.
+    const form = new FormData();
+    form.set('file', new Blob([Buffer.from('%PDF-1.4 fake')], { type: 'application/pdf' }), 'spec.pdf');
+    const uploadRes = await fetch(`${base}/api/v1/files`, {
+      method: 'POST',
+      headers: authHeaders(server as RunningServer),
+      body: form,
+    } as never);
+    const uploaded = (await uploadRes.json()) as Envelope<{ id: string }>;
+    expect(uploaded.code).toBe(0);
+
+    const { body } = await call<null>('POST', `/api/v1/sessions/${id}/prompts`, {
+      model: 'stub',
+      content: [
+        { type: 'text', text: 'watch this' },
+        { type: 'video', source: { kind: 'file', file_id: uploaded.data.id } },
+      ],
+    });
+    expect(body.code).toBe(40001);
+    expect(session!.accessor.get(IAgentLifecycleService).get('main')).toBeUndefined();
+  });
+
+  it('carries an uploaded video into the prompt as an internal kimi-file reference', async () => {
     const id = await createSession(home as string);
     await createMainAgent(id);
     const videoBytes = Buffer.from('tiny fake mp4 bytes');
@@ -235,16 +278,24 @@ describe('server-v2 /api/v1 prompts', () => {
     });
     expect(submitted.body.code).toBe(0);
 
-    const content = submitted.body.data.content as Array<{ type: string; text?: string }>;
+    // The edge no longer uploads to the provider. The queued prompt reprojects
+    // the video as the file reference it came from — a `{ kind: 'file' }` source
+    // is only ever produced from an internal `kimi-file://` url, so this proves
+    // the enqueued message carries the reference (its materialization path is
+    // never leaked back to the client).
+    const content = submitted.body.data.content as Array<Record<string, unknown>>;
     expect(content).toHaveLength(2);
     expect(content[0]).toEqual({ type: 'text', text: 'what happens in this video?' });
-    expect(content[1]?.type).toBe('text');
-    const match = /<video path="([^"]+)"><\/video>/.exec(content[1]?.text ?? '');
-    expect(match).not.toBeNull();
-    const cachePath = match![1]!;
-    expect(cachePath.startsWith(join(home as string, 'cache'))).toBe(true);
-    expect(cachePath.endsWith('.mp4')).toBe(true);
-    expect(await readFile(cachePath)).toEqual(videoBytes);
+    expect(content[1]).toEqual({
+      type: 'video',
+      source: { kind: 'file', file_id: uploaded.data.id },
+    });
+
+    // The `?path=` of that reference points at a materialized copy of the bytes
+    // (written during the submit), which the engine resolver falls back to when
+    // it cannot upload or inline the video.
+    const materialized = join(home as string, 'cache', `${uploaded.data.id}.mp4`);
+    expect(await readFile(materialized)).toEqual(videoBytes);
   });
 
   it('compresses uploaded image prompts into base64 image parts with a readback caption', async () => {