wtagent 0.4.0 → 1.0.0

package/README.md

@@ -1,8 +1,13 @@
 # WTAgent
 
-Use your web AI account as a local CLI agent.
+Turn ChatGPT Web (including Pro) into Codex.
+Turn Claude Web into Claude Code.
 
-WTAgent connects ChatGPT, Claude, DeepSeek, Gemini, Grok, Kimi, or GLM Web to your local project: the model reasons in the browser while WTAgent reads and writes local files and runs commands on your machine.
+Also DeepSeek, Gemini, Grok, Kimi, GLM.
+
+No API key. No MCP. No tunnel. No plugin.
+
+https://xixian42.github.io/wtagent/
 
 [中文](#中文)
 
@@ -24,7 +29,7 @@ cd wtagent-demo
 wtagent
 ```
 
-ChatGPT asks you to choose `Pro` or `Current`; other providers keep or silently select their configured default. Then type a task:
+After login, interactive runs give you five seconds to choose a model in the browser. Press Enter to continue immediately, or wait to keep the current selection. Then type a task:
 
 ```text
 $ wtagent
@@ -33,13 +38,86 @@ you › Create hello.js that writes "Hello from WTAgent" to hello.txt. Run it wi
 
 WTAgent creates the files in the current directory, runs the script locally, and checks its output. You can continue chatting in the same terminal after the task finishes.
 
-Choose a provider with `--model` (ChatGPT is the default). Supported values are `chatgpt`, `claude`, `deepseek`, `gemini`, `kimi`, and `glm`:
+Choose a provider with `--model` (ChatGPT is the default). Supported values are `chatgpt`, `claude`, `deepseek`, `gemini`, `grok`, `kimi`, and `glm`:
 
 ```bash
 wtagent --model claude "inspect this project and summarize its architecture"
 wtagent --model gemini "inspect this project and summarize its architecture"
 ```
 
+### Generate and save images
+
+Use ChatGPT, Gemini, or Grok to generate images in the current conversation. No
+extra image flag is needed; describe the image in your task:
+
+```bash
+wtagent --model chatgpt --once "Generate a square illustration of a blue robot watering a plant. Save it locally."
+wtagent --model gemini --once "Generate a 16:9 watercolor city skyline and save the image locally."
+wtagent --model grok --once "Generate a minimalist landscape illustration and save it locally."
+```
+
+WTAgent waits for the completed image reply, downloads its images, checks their
+format and dimensions, and records SHA-256 hashes. Supported file formats are
+PNG, JPEG, and WebP. Files are saved under the current project's
+`artifacts/native-images/<turn-id>/`, for example:
+
+```text
+artifacts/native-images/<turn-id>/image-1.png
+artifacts/native-images/<turn-id>/image-2.webp
+```
+
+The extension follows the downloaded file's actual format. Multiple images from
+one reply are saved separately. WTAgent passes the verified local paths back to
+the model, which can finish the task or continue with file operations such as
+organizing assets and building a page that uses them.
+
+In an interactive conversation, attach a local reference image with `@path`:
+
+```text
+you › @assets/reference.png Create a watercolor illustration based on this reference and save it locally.
+```
+
+Reference handling, image size, aspect ratio, and image availability depend on
+the website and selected model. WTAgent uses your logged-in account and its
+quota. A text-only explanation or refusal is returned as text; it is not reported
+as a saved image.
+
+If downloading or returning the saved paths is interrupted, resume the recorded
+session without adding a new instruction:
+
+```bash
+wtagent resume <session-id>
+```
+
+Recovery reuses the recorded reply when it can verify the conversation. It does
+not automatically repeat an image-generation request whose submission is
+uncertain. Partially downloaded replies may need to download their files again.
+
+### Generate music with Gemini
+
+```bash
+wtagent --model gemini --type music --once "Create peaceful instrumental piano music, no vocals"
+```
+
+`--type music` selects Gemini's native Music tool. Tracks are saved under
+`artifacts/music/<turn-id>/`. If Gemini returns an MP4 with audio and a cover
+video, WTAgent preserves that original; when `ffmpeg` is on PATH, it also extracts
+an `.m4a` audio file without re-encoding. Without FFmpeg, the original MP4 remains
+usable. Duration follows the provider's output.
+
+Download interruptions can be resumed with `wtagent resume <session-id>`. A bare
+resume of a completed music session returns its saved result without generating
+again. The default `--type agent` retains ordinary agent behavior, including
+native image output.
+
+### Conversation recovery and diagnostics
+
+The ChatGPT adapter supports legacy and modern message layouts, temporary
+conversation URLs, and virtualized history. When a send cannot be verified,
+WTAgent preserves the session for recovery. Structural failure reports identify
+the recognized page layout, missing identity fields, and send stage; the CLI
+shows the report path for startup, send-confirmation, and recovery failures.
+
 Claude keeps the model selected by claude.ai in its browser profile; WTAgent does not override it.
 Gemini likewise keeps the model selected in its browser profile.
 
@@ -57,7 +135,14 @@ Multiline paste and `↑` / `↓` input history are supported. Press `Ctrl+C` or
 
 ## 中文
 
-WTAgent 将 ChatGPT、Claude、DeepSeek、Gemini、Grok、Kimi 或 GLM 网页聊天连接到本地项目：模型在浏览器中思考，WTAgent 在你的电脑上读写本地文件并运行命令。
+把 ChatGPT 网页版（含 Pro）变成 Codex。
+把 Claude 网页版变成 Claude Code。
+
+同时支持 DeepSeek、Gemini、Grok、Kimi、GLM。
+
+无需 API Key，无需 MCP，无需隧道，无需插件。
+
+https://xixian42.github.io/wtagent/
 
 ### 快速开始
 
@@ -77,7 +162,7 @@ cd wtagent-demo
 wtagent
 ```
 
-ChatGPT 会让你选择 `Pro` 或 `Current`；其他 provider 会保持或自动选择配置的默认模式。然后直接输入任务：
+登录后，交互模式会留出 5 秒供你在浏览器里选择模型。按 Enter 可立即继续，等待倒计时结束则沿用当前选择。然后输入任务：
 
 ```text
 $ wtagent
@@ -86,13 +171,62 @@ you › 创建 hello.js，将“Hello from WTAgent”写入 hello.txt。用 Node
 
 WTAgent 会在当前目录创建文件、运行本地脚本并检查输出。任务完成后，可以继续在同一个终端中对话。
 
-通过 `--model` 选择 provider（默认是 ChatGPT）。可选值包括 `chatgpt`、`claude`、`deepseek`、`gemini`、`kimi` 和 `glm`：
+通过 `--model` 选择 provider（默认是 ChatGPT）。可选值包括 `chatgpt`、`claude`、`deepseek`、`gemini`、`grok`、`kimi` 和 `glm`：
 
 ```bash
 wtagent --model claude "分析这个项目并总结架构"
 wtagent --model gemini "分析这个项目并总结架构"
 ```
 
+### 生成图片并保存到本地
+
+使用 ChatGPT、Gemini 或 Grok，在当前对话中直接生成图片。无需额外的生图参数，在任务里描述要画的内容即可：
+
+```bash
+wtagent --model chatgpt --once "生成一张蓝色小机器人给盆栽浇水的方形插画，保存到本地"
+wtagent --model gemini --once "生成一张 16:9 的水彩城市天际线，保存到本地"
+wtagent --model grok --once "生成一张极简风格的山水插画，保存到本地"
+```
+
+WTAgent 等待图片回复完成后下载文件，检查格式和尺寸，并记录 SHA-256 哈希。支持 PNG、JPEG 和 WebP。文件保存在当前项目的 `artifacts/native-images/<turn-id>/` 目录，例如：
+
+```text
+artifacts/native-images/<turn-id>/image-1.png
+artifacts/native-images/<turn-id>/image-2.webp
+```
+
+扩展名以下载文件的实际格式为准。一条回复包含多张图片时，会分别保存。WTAgent 把经过验证的本地路径交回模型，模型可以结束任务，也可以继续整理素材、制作引用这些图片的页面等。
+
+在交互对话中，可以通过 `@路径` 附加本地参考图：
+
+```text
+你 › @assets/reference.png 参考这张图，生成水彩风格的插画并保存到本地。
+```
+
+是否支持参考图、图片尺寸、宽高比和图片生成，取决于网站及当前选择的模型。WTAgent 使用你已登录的账号和额度。若网站只返回文字说明或拒绝生成，会如实返回文字，不会声称已经保存图片。
+
+下载或回传文件路径时中断，可以不带新指令恢复原会话：
+
+```bash
+wtagent resume <session-id>
+```
+
+恢复时会核对会话并复用已记录的回复；无法确认是否已提交的生图请求不会自动重发。只下载了一部分图片的回复，恢复时可能需要重新下载文件。
+
+### 使用 Gemini 生成音乐
+
+```bash
+wtagent --model gemini --type music --once "生成一段舒缓钢琴纯音乐，不要人声"
+```
+
+`--type music` 会启用 Gemini 原生 Music 工具，文件保存到 `artifacts/music/<turn-id>/`。如果 Gemini 返回带封面画面和音轨的 MP4，WTAgent 会保留原文件；本机 PATH 中有 `ffmpeg` 时，还会在不重新编码的情况下提取 `.m4a` 纯音频。未安装 FFmpeg 时仍可使用原始 MP4，时长以网站实际生成结果为准。
+
+下载中断后，可用 `wtagent resume <session-id>` 继续。已完成的音乐会话不带新指令恢复时，会返回已保存的结果，不再生成一次。默认 `--type agent` 保持普通智能体行为，也支持直接接收图片。
+
+### 会话恢复与兼容诊断
+
+ChatGPT 适配器支持新旧消息结构、临时会话地址和只保留部分消息节点的长对话。无法确认发送结果时，会保留会话供恢复。结构化诊断会记录识别到的页面结构、缺失的消息身份字段和发送阶段；启动、发送确认或恢复失败时，终端会显示诊断文件路径。
+
 Claude 会沿用 claude.ai 在该浏览器 Profile 中选择的模型，WTAgent 不会自动切换模型。
 Gemini 同样沿用其浏览器 Profile 当前选择的模型。
 
@@ -108,6 +242,26 @@ wtagent "创建 hello.js，运行并验证输出"
 
 支持多行粘贴和 `↑` / `↓` 输入历史。使用 `Ctrl+C` 或 `Ctrl+D` 退出。
 
+## Development and regression tests / 开发与回归测试
+
+Run from a source checkout / 在源码目录运行：
+
+```bash
+npm ci
+npm test
+npm run check
+npm run test:media
+npm run test:chatgpt-dom
+```
+
+`test:media` covers image downloads, native multi-image replies, interrupted
+recovery, music handling, and provider DOM behavior. The browser tests require
+Chrome/Chromium (or `WTAGENT_CHROME_PATH`), use isolated test pages, and do not
+require a web account or consume generation quota. They do not replace live
+account testing when a provider changes its service.
+
+`test:media` 覆盖图片下载、多图回复、中断恢复、音乐处理和各网站的 DOM 行为。浏览器测试需要 Chrome/Chromium，也可通过 `WTAGENT_CHROME_PATH` 指定路径；测试使用隔离页面，无需账号，也不消耗生成额度。网站服务变化后的真实账号验证仍需单独进行。
+
 ## License
 
 [MIT](./LICENSE)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wtagent",
-  "version": "0.4.0",
-  "description": "Turn your own web AI session into a local tool-using agent.",
+  "version": "1.0.0",
+  "description": "Turn ChatGPT Web (including Pro) into Codex. Turn Claude Web into Claude Code. Also DeepSeek, Gemini, Grok, Kimi, GLM. No API key, no MCP, no tunnel, no plugin.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/XiXian42/wtagent.git"
@@ -25,7 +25,6 @@
   "files": [
     "src",
     "README.md",
-    "docs/technical-design.md",
     "LICENSE"
   ],
   "scripts": {
@@ -38,7 +37,9 @@
     "login": "node src/cli/main.js login",
     "prepack": "npm run check && npm test",
     "release": "npm publish --tag latest",
-    "release:alpha": "npm publish --tag alpha"
+    "release:alpha": "npm publish --tag alpha",
+    "test:chatgpt-dom": "node scripts/test-chatgpt-dom.js",
+    "test:media": "node scripts/test-media.js"
   },
   "engines": {
     "node": "^20.17.0 || ^22.13.0 || >=23.5.0"

package/src/artifacts/artifact-store.js

@@ -0,0 +1,154 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { replaceFileAtomic } from "../shared/atomic-write.js";
+import { inspectMusicBuffer } from "../audio/music-artifact.js";
+import {
+  resolveCanonicalWriteTarget,
+  resolveToolPath,
+} from "../policy/path-guard.js";
+
+const SIGNATURES = Object.freeze([
+  { mimeType: "image/png", extension: ".png", matches: (b) => b.length >= 24 && b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) },
+  { mimeType: "image/jpeg", extension: ".jpg", matches: (b) => b.length >= 4 && b[0] === 0xff && b[1] === 0xd8 && b.at(-2) === 0xff && b.at(-1) === 0xd9 },
+  { mimeType: "image/webp", extension: ".webp", matches: (b) => b.length >= 16 && b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WEBP" },
+]);
+
+function pngDimensions(buffer) {
+  return buffer.length >= 24
+    ? { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) }
+    : {};
+}
+
+function jpegDimensions(buffer) {
+  let offset = 2;
+  while (offset + 9 < buffer.length) {
+    if (buffer[offset] !== 0xff) {
+      offset += 1;
+      continue;
+    }
+    const marker = buffer[offset + 1];
+    offset += 2;
+    if (marker === 0xd8 || marker === 0xd9 || marker === 0x01) continue;
+    if (offset + 2 > buffer.length) break;
+    const length = buffer.readUInt16BE(offset);
+    if (length < 2 || offset + length > buffer.length) break;
+    if ([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf].includes(marker)) {
+      return {
+        height: buffer.readUInt16BE(offset + 3),
+        width: buffer.readUInt16BE(offset + 5),
+      };
+    }
+    offset += length;
+  }
+  return {};
+}
+
+function webpDimensions(buffer) {
+  const kind = buffer.toString("ascii", 12, 16);
+  if (kind === "VP8X" && buffer.length >= 30) {
+    return {
+      width: 1 + buffer.readUIntLE(24, 3),
+      height: 1 + buffer.readUIntLE(27, 3),
+    };
+  }
+  if (kind === "VP8L" && buffer.length >= 25) {
+    const bits = buffer.readUInt32LE(21);
+    return {
+      width: (bits & 0x3fff) + 1,
+      height: ((bits >>> 14) & 0x3fff) + 1,
+    };
+  }
+  if (kind === "VP8 " && buffer.length >= 30) {
+    return {
+      width: buffer.readUInt16LE(26) & 0x3fff,
+      height: buffer.readUInt16LE(28) & 0x3fff,
+    };
+  }
+  return {};
+}
+
+export function inspectImageBuffer(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length === 0) {
+    throw new Error("The provider returned an empty image artifact.");
+  }
+  const format = SIGNATURES.find((entry) => entry.matches(buffer));
+  if (!format) {
+    throw new Error("The downloaded artifact is not a supported PNG, JPEG, or WebP image.");
+  }
+  const dimensions = format.mimeType === "image/png"
+    ? pngDimensions(buffer)
+    : format.mimeType === "image/jpeg"
+      ? jpegDimensions(buffer)
+      : webpDimensions(buffer);
+  if (!Number.isSafeInteger(dimensions.width) || !Number.isSafeInteger(dimensions.height)
+      || dimensions.width <= 0 || dimensions.height <= 0) {
+    throw new Error(`Could not read dimensions from ${format.mimeType} artifact.`);
+  }
+  return {
+    ...format,
+    ...dimensions,
+    size: buffer.length,
+    sha256: createHash("sha256").update(buffer).digest("hex"),
+  };
+}
+
+export class ArtifactStore {
+  constructor({ projectRoot, allowOutside = false }) {
+    this.projectRoot = path.resolve(projectRoot);
+    this.allowOutside = allowOutside;
+  }
+
+  async resolveOutputPath(rawPath) {
+    const info = await resolveToolPath(this.projectRoot, rawPath);
+    if (!info.inside && !this.allowOutside) {
+      throw new Error(`Path is outside project root: ${info.path}`);
+    }
+    await fs.mkdir(path.dirname(info.path), { recursive: true });
+    return await resolveCanonicalWriteTarget(this.projectRoot, info.path, {
+      allowOutside: this.allowOutside,
+    });
+  }
+
+  async saveImage(sourcePath, outputPath, provenance = {}) {
+    return await this.saveValidatedMedia(sourcePath, outputPath, provenance, inspectImageBuffer, "image");
+  }
+
+  async saveMusic(sourcePath, outputPath, provenance = {}) {
+    return await this.saveValidatedMedia(sourcePath, outputPath, provenance, inspectMusicBuffer, "music");
+  }
+
+  async saveValidatedMedia(sourcePath, outputPath, provenance, inspect, type) {
+    const target = await this.resolveOutputPath(outputPath);
+    const buffer = await fs.readFile(sourcePath);
+    const inspected = inspect(buffer);
+    const requestedExtension = path.extname(target).toLowerCase();
+    const acceptedExtensions = inspected.mimeType === "image/jpeg"
+      ? new Set([".jpg", ".jpeg"])
+      : new Set([inspected.extension]);
+    if (requestedExtension && !acceptedExtensions.has(requestedExtension)) {
+      throw new Error(
+        `Output extension ${requestedExtension} does not match downloaded ${inspected.mimeType}.`,
+      );
+    }
+    const temporary = `${target}.wtagent-${process.pid}-${randomUUID()}.tmp`;
+    try {
+      await fs.copyFile(sourcePath, temporary);
+      await replaceFileAtomic(temporary, target);
+    } finally {
+      await fs.rm(temporary, { force: true }).catch(() => null);
+    }
+    return {
+      id: `artifact_${inspected.sha256.slice(0, 20)}`,
+      type,
+      localPath: target,
+      mimeType: inspected.mimeType,
+      width: inspected.width,
+      height: inspected.height,
+      ...(type === "music" ? { durationSeconds: inspected.durationSeconds, hasVideo: inspected.hasVideo } : {}),
+      size: inspected.size,
+      sha256: inspected.sha256,
+      provenance,
+    };
+  }
+}

package/src/audio/music-artifact.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+
+function boxes(buffer, start = 0, end = buffer.length) {
+  const result = [];
+  for (let offset = start; offset < end;) {
+    if (offset + 8 > end) throw new Error("Truncated music container.");
+    let size = buffer.readUInt32BE(offset);
+    let header = 8;
+    if (size === 1) {
+      if (offset + 16 > end) throw new Error("Truncated music container.");
+      size = Number(buffer.readBigUInt64BE(offset + 8));
+      header = 16;
+    } else if (size === 0) size = end - offset;
+    if (!Number.isSafeInteger(size) || size < header || offset + size > end) {
+      throw new Error("Invalid music container size.");
+    }
+    result.push({ type: buffer.toString("ascii", offset + 4, offset + 8), start: offset + header, end: offset + size });
+    offset += size;
+  }
+  return result;
+}
+
+// Gemini's Music player currently serves an MP4 containing cover video and AAC.
+// Check the actual audio track, not the URL suffix or the provider's caption.
+export function inspectMusicBuffer(buffer) {
+  const top = boxes(buffer);
+  const moov = top.find((box) => box.type === "moov");
+  if (!top.some((box) => box.type === "ftyp") || !moov
+      || !top.some((box) => box.type === "mdat" && box.end > box.start)) {
+    throw new Error("The downloaded music is not a complete MP4/M4A file.");
+  }
+  const tracks = boxes(buffer, moov.start, moov.end).filter((box) => box.type === "trak");
+  const handlers = [];
+  let durationSeconds = null;
+  for (const track of tracks) {
+    const mdia = boxes(buffer, track.start, track.end).find((box) => box.type === "mdia");
+    if (!mdia) continue;
+    const children = boxes(buffer, mdia.start, mdia.end);
+    const hdlr = children.find((box) => box.type === "hdlr");
+    if (!hdlr || hdlr.start + 12 > hdlr.end) continue;
+    const handler = buffer.toString("ascii", hdlr.start + 8, hdlr.start + 12);
+    handlers.push(handler);
+    if (handler !== "soun") continue;
+    const mdhd = children.find((box) => box.type === "mdhd");
+    if (!mdhd) continue;
+    const version = buffer[mdhd.start];
+    const timeOffset = mdhd.start + (version === 1 ? 20 : 12);
+    if (![0, 1].includes(version) || timeOffset + (version === 1 ? 12 : 8) > mdhd.end) continue;
+    const scale = buffer.readUInt32BE(timeOffset);
+    const duration = version === 1
+      ? Number(buffer.readBigUInt64BE(timeOffset + 4)) : buffer.readUInt32BE(timeOffset + 4);
+    if (scale > 0 && duration > 0) durationSeconds = duration / scale;
+  }
+  if (!handlers.includes("soun") || !Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    throw new Error("The downloaded music file has no valid audio track.");
+  }
+  const hasVideo = handlers.includes("vide");
+  return {
+    mimeType: hasVideo ? "video/mp4" : "audio/mp4",
+    extension: hasVideo ? ".mp4" : ".m4a",
+    durationSeconds,
+    hasVideo,
+    size: buffer.length,
+    sha256: createHash("sha256").update(buffer).digest("hex"),
+  };
+}

package/src/audio/native-music-receiver.js

@@ -0,0 +1,91 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ArtifactStore } from "../artifacts/artifact-store.js";
+import { inspectMusicBuffer } from "./music-artifact.js";
+
+const execFileAsync = promisify(execFile);
+export const MUSIC_SYSTEM_REMINDER = "Use Gemini's native Music tool to create the requested playable music. "
+  + "Return the generated track directly, with an optional short description. Do not use XML, code, or local tools. "
+  + "If music cannot be generated, explain the limitation plainly. WTAgent downloads the generated file automatically.";
+
+export function validateGenerationType(type, provider) {
+  const value = type ?? "agent";
+  if (!["agent", "music"].includes(value)) throw new Error(`Unknown --type ${value}. Use agent or music.`);
+  if (value === "music" && provider !== "gemini") throw new Error("--type music requires --model gemini.");
+  return value;
+}
+
+export class NativeMusicReceiver {
+  constructor({ adapter, extractAudio = extractAudioTrack }) {
+    this.adapter = adapter;
+    this.extractAudio = extractAudio;
+  }
+
+  async prepare() {
+    await this.adapter.prepareMusicGeneration();
+  }
+
+  async read(message) {
+    return await message.locator("video, audio").evaluateAll((elements) => ({
+      pending: elements.some((element) => !element.currentSrc && !element.src),
+      music: elements.filter((element) => element.isConnected && (element.currentSrc || element.src))
+        .map((element) => ({ source: element.currentSrc || element.src })),
+    }));
+  }
+
+  async save(tracks, { projectRoot, handoffId, assistantMessageId }) {
+    const store = new ArtifactStore({ projectRoot });
+    const directory = path.join("artifacts", "music", createHash("sha256").update(handoffId).digest("hex").slice(0, 24));
+    const temporaryDir = await fs.mkdtemp(path.join(os.tmpdir(), "wtagent-music-"));
+    const artifacts = [];
+    try {
+      for (const [index, track] of tracks.entries()) {
+        const url = new URL(track.source);
+        if (url.protocol !== "https:" || !(url.hostname === "contribution.usercontent.google.com"
+            || url.hostname.endsWith(".googleusercontent.com"))) {
+          throw new Error("The music source is not a supported Gemini media URL.");
+        }
+        const response = await this.adapter.page.request.get(track.source, { timeout: 60_000 });
+        if (!response.ok()) throw new Error(`Music download failed with HTTP ${response.status()}.`);
+        const body = await response.body();
+        const inspected = inspectMusicBuffer(body);
+        const source = path.join(temporaryDir, `track-${index + 1}${inspected.extension}`);
+        await fs.writeFile(source, body);
+        const provenance = { provider: "gemini", assistantMessageId, source: track.source };
+        const original = await store.saveMusic(source, path.join(directory, path.basename(source)), provenance);
+        artifacts.push(original);
+        if (inspected.hasVideo) {
+          const audioPath = path.join(temporaryDir, `track-${index + 1}.m4a`);
+          const extraction = await this.extractAudio(source, audioPath);
+          if (extraction.ok) {
+            artifacts.push(await store.saveMusic(audioPath, path.join(directory, path.basename(audioPath)), {
+              ...provenance, extractedFrom: original.localPath, lossless: true,
+            }));
+          } else {
+            original.audioExtractionNote = extraction.message;
+          }
+        }
+      }
+      return artifacts;
+    } finally {
+      await fs.rm(temporaryDir, { recursive: true, force: true });
+    }
+  }
+}
+
+async function extractAudioTrack(source, output) {
+  try {
+    await execFileAsync("ffmpeg", ["-nostdin", "-v", "error", "-n", "-i", source, "-map", "0:a:0", "-vn", "-c:a", "copy", output], {
+      timeout: 60_000, maxBuffer: 1024 * 1024, windowsHide: true,
+    });
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, message: error.code === "ENOENT"
+      ? "FFmpeg is not installed; the original MP4 with its audio track was saved."
+      : "Audio extraction failed; the original MP4 with its audio track was saved." };
+  }
+}