iris-chatbot 0.2.4

package/template/src/lib/tooling/tools/music.ts

@@ -0,0 +1,988 @@
+import { ensureMacOS } from "../safety";
+import { runCommandSafe } from "../runtime";
+import type { ToolDefinition, ToolExecutionContext } from "../types";
+
+type MusicPlayInput = {
+  query?: string;
+  title?: string;
+  artist?: string;
+  source?: "apple_music" | "local_library";
+};
+
+type MusicSetVolumeInput = {
+  level?: number;
+  target?: "system" | "music";
+};
+
+type LibraryTrackCandidate = {
+  persistentId: string;
+  title: string;
+  artist: string;
+  album: string;
+};
+
+type LibraryTrackScore = {
+  candidate: LibraryTrackCandidate;
+  score: number;
+};
+
+type LibraryPlaylistCandidate = {
+  persistentId: string;
+  name: string;
+};
+
+type LibraryPlaylistScore = {
+  candidate: LibraryPlaylistCandidate;
+  score: number;
+};
+
+const APPLESCRIPT_TIMEOUT_MS = 30_000;
+const MAX_LIBRARY_CANDIDATES_PER_QUERY = 30;
+const MAX_PLAYBACK_ATTEMPTS = 3;
+
+function asObject(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== "object") {
+    throw new Error("Tool input must be an object.");
+  }
+  return input as Record<string, unknown>;
+}
+
+function asNumber(input: unknown, field: string): number {
+  if (typeof input !== "number" || !Number.isFinite(input)) {
+    throw new Error(`Missing required numeric field: ${field}`);
+  }
+  return input;
+}
+
+function normalizeLoose(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function normalizeSearchText(value: string): string {
+  return value
+    .replace(/[’']/g, "")
+    .replace(/[^a-zA-Z0-9]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function splitNormalizedTokens(value: string): string[] {
+  const normalized = normalizeSearchText(value).toLowerCase();
+  if (!normalized) {
+    return [];
+  }
+  return normalized.split(" ").filter(Boolean);
+}
+
+function dedupeList(values: string[]): string[] {
+  const seen = new Set<string>();
+  const output: string[] = [];
+  for (const value of values) {
+    const normalized = value.trim();
+    if (!normalized) {
+      continue;
+    }
+    const key = normalized.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    output.push(normalized);
+  }
+  return output;
+}
+
+function buildSearchQueries(params: {
+  query: string;
+  title: string;
+  artist: string;
+}): string[] {
+  const candidates: string[] = [];
+  const pushWithForms = (value: string) => {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return;
+    }
+    const compact = normalizeSearchText(trimmed);
+    candidates.push(trimmed);
+    if (compact && compact.toLowerCase() !== trimmed.toLowerCase()) {
+      candidates.push(compact);
+    }
+  };
+
+  if (params.title && params.artist) {
+    pushWithForms(`${params.title} ${params.artist}`);
+    pushWithForms(`${params.artist} ${params.title}`);
+  }
+  if (params.query) {
+    pushWithForms(params.query);
+  }
+  if (params.title) {
+    pushWithForms(params.title);
+  }
+  if (params.artist) {
+    pushWithForms(params.artist);
+  }
+
+  return dedupeList(candidates).filter((value) => value.length >= 2);
+}
+
+function normalizePlaylistNeedle(value: string): string {
+  return value
+    .replace(/\b(play|playlist|playlists|music|songs|song|track|tracks|please|for me)\b/gi, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function buildPlaylistQueries(params: {
+  query: string;
+  title: string;
+  artist: string;
+  rawQuery: string;
+}): string[] {
+  const candidates = [
+    params.query,
+    normalizePlaylistNeedle(params.query),
+    params.rawQuery,
+    normalizePlaylistNeedle(params.rawQuery),
+    params.title,
+    normalizePlaylistNeedle(params.title),
+  ].filter((value) => value.trim().length > 0);
+
+  // Playlists are named text, so keep slightly shorter inputs for partial matches.
+  return dedupeList(candidates).filter((value) => value.length >= 1);
+}
+
+function textMatchScore(actual: string, requested: string): number {
+  const normalizedActual = normalizeLoose(actual);
+  const normalizedRequested = normalizeLoose(requested);
+  if (!normalizedActual || !normalizedRequested) {
+    return 0;
+  }
+  if (normalizedActual === normalizedRequested) {
+    return 100;
+  }
+  if (
+    normalizedActual.includes(normalizedRequested) ||
+    normalizedRequested.includes(normalizedActual)
+  ) {
+    return 75;
+  }
+
+  const requestedTokens = splitNormalizedTokens(requested);
+  const actualTokens = splitNormalizedTokens(actual);
+  if (requestedTokens.length === 0 || actualTokens.length === 0) {
+    return 0;
+  }
+
+  const actualTokenSet = new Set(actualTokens);
+  let overlap = 0;
+  for (const token of requestedTokens) {
+    if (actualTokenSet.has(token)) {
+      overlap += 1;
+    }
+  }
+
+  const ratio = overlap / requestedTokens.length;
+  if (ratio >= 1) {
+    return 65;
+  }
+  if (ratio >= 0.75) {
+    return 45;
+  }
+  if (ratio >= 0.5) {
+    return 25;
+  }
+  return 0;
+}
+
+function isLikelyTextMatch(actual: string, requested: string): boolean {
+  return textMatchScore(actual, requested) >= 45;
+}
+
+function rankLibraryCandidates(params: {
+  candidates: LibraryTrackCandidate[];
+  query: string;
+  title: string;
+  artist: string;
+  enforceTitleMatch: boolean;
+  enforceArtistMatch: boolean;
+}): LibraryTrackScore[] {
+  const scores: LibraryTrackScore[] = [];
+
+  for (const candidate of params.candidates) {
+    const titleScore = textMatchScore(candidate.title, params.title);
+    const artistScore = textMatchScore(candidate.artist, params.artist);
+    const queryScore = textMatchScore(
+      `${candidate.title} ${candidate.artist}`,
+      params.query,
+    );
+
+    if (params.enforceTitleMatch && params.title && titleScore < 45) {
+      continue;
+    }
+    if (params.enforceArtistMatch && params.artist && artistScore < 35) {
+      continue;
+    }
+
+    const score = titleScore * 1.8 + artistScore * 1.5 + queryScore * 0.9;
+    scores.push({ candidate, score });
+  }
+
+  return scores.sort((a, b) => b.score - a.score);
+}
+
+function rankPlaylistCandidates(params: {
+  candidates: LibraryPlaylistCandidate[];
+  query: string;
+  rawQuery: string;
+  playlistRequested: boolean;
+}): LibraryPlaylistScore[] {
+  const cleanedQuery = normalizePlaylistNeedle(params.query) || params.query;
+  const cleanedRaw = normalizePlaylistNeedle(params.rawQuery) || params.rawQuery;
+  const scores: LibraryPlaylistScore[] = [];
+
+  for (const candidate of params.candidates) {
+    const queryScore = textMatchScore(candidate.name, cleanedQuery);
+    const rawScore = textMatchScore(candidate.name, cleanedRaw);
+    const exactBonus =
+      normalizeLoose(candidate.name) === normalizeLoose(cleanedQuery) ||
+      normalizeLoose(candidate.name) === normalizeLoose(cleanedRaw)
+        ? 30
+        : 0;
+    const playlistBonus = params.playlistRequested ? 20 : 0;
+    const score = queryScore * 1.8 + rawScore * 1.2 + exactBonus + playlistBonus;
+    scores.push({ candidate, score });
+  }
+
+  return scores.sort((a, b) => b.score - a.score);
+}
+
+
+async function runAppleScript(script: string, args: string[] = [], signal?: AbortSignal) {
+  const { stdout } = await runCommandSafe({
+    command: "osascript",
+    args: ["-e", script, ...args],
+    signal,
+    timeoutMs: APPLESCRIPT_TIMEOUT_MS,
+  });
+  return stdout;
+}
+
+async function searchLibraryTracks(
+  queries: string[],
+  signal?: AbortSignal,
+): Promise<LibraryTrackCandidate[]> {
+  if (queries.length === 0) {
+    return [];
+  }
+
+  const script =
+    "on run argv\n" +
+    `set perQueryLimit to ${MAX_LIBRARY_CANDIDATES_PER_QUERY}\n` +
+    'set outText to ""\n' +
+    'tell application "Music"\n' +
+    'set libraryList to library playlist 1\n' +
+    "repeat with term in argv\n" +
+    'set q to term as text\n' +
+    'if q is not "" then\n' +
+    "try\n" +
+    'set foundTracks to (search libraryList for q)\n' +
+    "set emitted to 0\n" +
+    "repeat with t in foundTracks\n" +
+    'set outText to outText & (persistent ID of t as text) & tab & (name of t as text) & tab & (artist of t as text) & tab & (album of t as text) & linefeed\n' +
+    "set emitted to emitted + 1\n" +
+    "if emitted is greater than or equal to perQueryLimit then exit repeat\n" +
+    "end repeat\n" +
+    "end try\n" +
+    "end if\n" +
+    "end repeat\n" +
+    "end tell\n" +
+    "return outText\n" +
+    "end run";
+
+  const output = await runAppleScript(script, queries, signal);
+  const byId = new Map<string, LibraryTrackCandidate>();
+
+  for (const line of output.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const [persistentId, title, artist, album] = trimmed.split("\t");
+    if (!persistentId || !title) {
+      continue;
+    }
+    if (!byId.has(persistentId)) {
+      byId.set(persistentId, {
+        persistentId,
+        title: title.trim(),
+        artist: (artist ?? "").trim(),
+        album: (album ?? "").trim(),
+      });
+    }
+  }
+
+  return [...byId.values()];
+}
+
+async function searchLibraryTracksByMetadata(params: {
+  title: string;
+  artist: string;
+  query: string;
+  signal?: AbortSignal;
+}): Promise<LibraryTrackCandidate[]> {
+  const titleNeedle = params.title.trim();
+  const artistNeedle = params.artist.trim();
+  const queryNeedle = params.query.trim();
+
+  if (!titleNeedle && !artistNeedle && !queryNeedle) {
+    return [];
+  }
+
+  const perQueryLimit = Math.max(40, MAX_LIBRARY_CANDIDATES_PER_QUERY * 2);
+  const script =
+    "on run argv\n" +
+    'set titleNeedle to item 1 of argv\n' +
+    'set artistNeedle to item 2 of argv\n' +
+    'set queryNeedle to item 3 of argv\n' +
+    `set perQueryLimit to ${perQueryLimit}\n` +
+    'set outText to ""\n' +
+    'tell application "Music"\n' +
+    'set libraryList to library playlist 1\n' +
+    "set foundTracks to {}\n" +
+    "if titleNeedle is not \"\" and artistNeedle is not \"\" then\n" +
+    "try\n" +
+    'set foundTracks to (every track of libraryList whose name contains titleNeedle and artist contains artistNeedle)\n' +
+    "end try\n" +
+    "else if titleNeedle is not \"\" then\n" +
+    "try\n" +
+    'set foundTracks to (every track of libraryList whose name contains titleNeedle)\n' +
+    "end try\n" +
+    "else if artistNeedle is not \"\" then\n" +
+    "try\n" +
+    'set foundTracks to (every track of libraryList whose artist contains artistNeedle)\n' +
+    "end try\n" +
+    "else if queryNeedle is not \"\" then\n" +
+    "try\n" +
+    'set foundTracks to (search libraryList for queryNeedle)\n' +
+    "end try\n" +
+    "end if\n" +
+    "set emitted to 0\n" +
+    "repeat with t in foundTracks\n" +
+    "try\n" +
+    'set outText to outText & (persistent ID of t as text) & tab & (name of t as text) & tab & (artist of t as text) & tab & (album of t as text) & linefeed\n' +
+    "set emitted to emitted + 1\n" +
+    "if emitted is greater than or equal to perQueryLimit then exit repeat\n" +
+    "end try\n" +
+    "end repeat\n" +
+    "end tell\n" +
+    "return outText\n" +
+    "end run";
+
+  const output = await runAppleScript(script, [titleNeedle, artistNeedle, queryNeedle], params.signal);
+  const byId = new Map<string, LibraryTrackCandidate>();
+
+  for (const line of output.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const [persistentId, title, artist, album] = trimmed.split("\t");
+    if (!persistentId || !title) {
+      continue;
+    }
+    if (!byId.has(persistentId)) {
+      byId.set(persistentId, {
+        persistentId,
+        title: title.trim(),
+        artist: (artist ?? "").trim(),
+        album: (album ?? "").trim(),
+      });
+    }
+  }
+
+  return [...byId.values()];
+}
+
+async function searchLibraryPlaylists(
+  queries: string[],
+  signal?: AbortSignal,
+): Promise<LibraryPlaylistCandidate[]> {
+  if (queries.length === 0) {
+    return [];
+  }
+
+  const perQueryLimit = Math.max(30, MAX_LIBRARY_CANDIDATES_PER_QUERY);
+  const script =
+    "on run argv\n" +
+    `set perQueryLimit to ${perQueryLimit}\n` +
+    'set outText to ""\n' +
+    'tell application "Music"\n' +
+    "repeat with term in argv\n" +
+    'set q to term as text\n' +
+    'if q is not "" then\n' +
+    "try\n" +
+    'set foundPlaylists to (every user playlist whose name contains q)\n' +
+    "set emitted to 0\n" +
+    "repeat with p in foundPlaylists\n" +
+    "try\n" +
+    'set outText to outText & (persistent ID of p as text) & tab & (name of p as text) & linefeed\n' +
+    "set emitted to emitted + 1\n" +
+    "if emitted is greater than or equal to perQueryLimit then exit repeat\n" +
+    "end try\n" +
+    "end repeat\n" +
+    "end try\n" +
+    "end if\n" +
+    "end repeat\n" +
+    "end tell\n" +
+    "return outText\n" +
+    "end run";
+
+  const output = await runAppleScript(script, queries, signal);
+  const byId = new Map<string, LibraryPlaylistCandidate>();
+  for (const line of output.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const [persistentId, name] = trimmed.split("\t");
+    if (!persistentId || !name) {
+      continue;
+    }
+    if (!byId.has(persistentId)) {
+      byId.set(persistentId, {
+        persistentId: persistentId.trim(),
+        name: name.trim(),
+      });
+    }
+  }
+  return [...byId.values()];
+}
+
+async function playLibraryPlaylistByPersistentId(
+  persistentId: string,
+  signal?: AbortSignal,
+): Promise<{
+  playing: boolean;
+  playlistName: string | null;
+  title: string | null;
+  artist: string | null;
+  album: string | null;
+}> {
+  const script =
+    "on run argv\n" +
+    'set requestedId to item 1 of argv\n' +
+    'tell application "Music"\n' +
+    'set selectedPlaylist to missing value\n' +
+    "try\n" +
+    'set matches to (every user playlist whose persistent ID is requestedId)\n' +
+    'if (count of matches) > 0 then set selectedPlaylist to item 1 of matches\n' +
+    "end try\n" +
+    'if selectedPlaylist is missing value then return "not_found"\n' +
+    "play selectedPlaylist\n" +
+    "delay 1.1\n" +
+    'set pState to player state as text\n' +
+    'if pState is not "playing" then return "not_playing"\n' +
+    'set pName to (name of selectedPlaylist as text)\n' +
+    'set tName to ""\n' +
+    'set tArtist to ""\n' +
+    'set tAlbum to ""\n' +
+    "try\n" +
+    'set tName to (name of current track as text)\n' +
+    'set tArtist to (artist of current track as text)\n' +
+    'set tAlbum to (album of current track as text)\n' +
+    "end try\n" +
+    'return "ok" & tab & pName & tab & tName & tab & tArtist & tab & tAlbum\n' +
+    "end tell\n" +
+    "end run";
+
+  const output = await runAppleScript(script, [persistentId], signal);
+  if (output === "not_found" || output === "not_playing") {
+    return {
+      playing: false,
+      playlistName: null,
+      title: null,
+      artist: null,
+      album: null,
+    };
+  }
+  const [, playlistName, title, artist, album] = output.split("\t");
+  return {
+    playing: true,
+    playlistName: playlistName?.trim() || null,
+    title: title?.trim() || null,
+    artist: artist?.trim() || null,
+    album: album?.trim() || null,
+  };
+}
+
+async function playLibraryTrackByPersistentId(
+  persistentId: string,
+  signal?: AbortSignal,
+): Promise<{
+  playing: boolean;
+  title: string | null;
+  artist: string | null;
+  album: string | null;
+}> {
+  const script =
+    "on run argv\n" +
+    'set requestedId to item 1 of argv\n' +
+    'tell application "Music"\n' +
+    'set selectedTrack to missing value\n' +
+    "try\n" +
+    'set matches to (every track of library playlist 1 whose persistent ID is requestedId)\n' +
+    'if (count of matches) > 0 then set selectedTrack to item 1 of matches\n' +
+    "end try\n" +
+    'if selectedTrack is missing value then return "not_found"\n' +
+    "play selectedTrack\n" +
+    "delay 1.2\n" +
+    'set pState to player state as text\n' +
+    'if pState is not "playing" then return "not_playing"\n' +
+    'set tName to ""\n' +
+    'set tArtist to ""\n' +
+    'set tAlbum to ""\n' +
+    "try\n" +
+    'set tName to (name of current track as text)\n' +
+    'set tArtist to (artist of current track as text)\n' +
+    'set tAlbum to (album of current track as text)\n' +
+    "on error\n" +
+    'set tName to (name of selectedTrack as text)\n' +
+    'set tArtist to (artist of selectedTrack as text)\n' +
+    'set tAlbum to (album of selectedTrack as text)\n' +
+    "end try\n" +
+    'return "ok" & tab & tName & tab & tArtist & tab & tAlbum\n' +
+    "end tell\n" +
+    "end run";
+
+  const output = await runAppleScript(script, [persistentId], signal);
+  if (output === "not_found" || output === "not_playing") {
+    return { playing: false, title: null, artist: null, album: null };
+  }
+  const [, title, artist, album] = output.split("\t");
+  return {
+    playing: true,
+    title: title?.trim() || null,
+    artist: artist?.trim() || null,
+    album: album?.trim() || null,
+  };
+}
+
+function matchesRequestedTrack(params: {
+  nowTitle: string;
+  nowArtist: string;
+  requestedTitle: string;
+  requestedArtist: string;
+  enforceTitleMatch: boolean;
+  enforceArtistMatch: boolean;
+}): boolean {
+  if (params.enforceTitleMatch && params.requestedTitle) {
+    if (!isLikelyTextMatch(params.nowTitle, params.requestedTitle)) {
+      return false;
+    }
+  }
+  if (params.enforceArtistMatch && params.requestedArtist) {
+    if (!isLikelyTextMatch(params.nowArtist, params.requestedArtist)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function runMusicPlay(input: unknown, context: ToolExecutionContext) {
+  ensureMacOS("Music automation");
+  const payload = asObject(input) as MusicPlayInput;
+  const rawQuery = typeof payload.query === "string" ? payload.query.trim() : "";
+  let title = typeof payload.title === "string" ? payload.title.trim() : "";
+  let artist = typeof payload.artist === "string" ? payload.artist.trim() : "";
+
+  if (!title && rawQuery) {
+    const byMatch = rawQuery.match(/^(.+?)\s+by\s+(.+)$/i);
+    if (byMatch?.[1]) {
+      title = byMatch[1].trim();
+      if (!artist && byMatch[2]) {
+        artist = byMatch[2].trim();
+      }
+    }
+  }
+  const query = rawQuery || [title, artist].filter(Boolean).join(" ").trim();
+  const playlistRequested = /\bplaylist\b/i.test(rawQuery);
+
+  const enforceArtistMatch = Boolean(artist);
+  const enforceTitleMatch =
+    Boolean(title) &&
+    (enforceArtistMatch || !rawQuery || normalizeLoose(rawQuery) !== normalizeLoose(title));
+
+  if (context.localTools.dryRun) {
+    return {
+      dryRun: true,
+      action: "music_play",
+      query,
+      title,
+      artist,
+      source: payload.source ?? "apple_music",
+    };
+  }
+
+  if (!query) {
+    const resumeScript =
+      'tell application "Music"\n' +
+      "play\n" +
+      "delay 1\n" +
+      'set pState to player state as text\n' +
+      'if pState is not "playing" then return "not_playing"\n' +
+      'set tName to ""\n' +
+      'set tArtist to ""\n' +
+      'set tAlbum to ""\n' +
+      "try\n" +
+      'set tName to (name of current track as text)\n' +
+      'set tArtist to (artist of current track as text)\n' +
+      'set tAlbum to (album of current track as text)\n' +
+      "end try\n" +
+      'return "ok" & tab & tName & tab & tArtist & tab & tAlbum\n' +
+      "end tell";
+    const output = await runAppleScript(resumeScript, [], context.signal);
+    if (output === "not_playing") {
+      return {
+        playing: false,
+        query: null,
+        title: null,
+        artist: null,
+        reason: "No active track was available to resume.",
+      };
+    }
+    const [, nowTitle, nowArtist, nowAlbum] = output.split("\t");
+    return {
+      playing: true,
+      matched: true,
+      query: null,
+      title: nowTitle || null,
+      artist: nowArtist || null,
+      album: nowAlbum || null,
+    };
+  }
+
+  const searchQueries = buildSearchQueries({
+    query,
+    title,
+    artist,
+  });
+  const primaryLibraryCandidates = await searchLibraryTracks(searchQueries, context.signal);
+  let libraryCandidates = primaryLibraryCandidates;
+  if (libraryCandidates.length === 0 || enforceTitleMatch || enforceArtistMatch) {
+    try {
+      const metadataCandidates = await searchLibraryTracksByMetadata({
+        title,
+        artist,
+        query,
+        signal: context.signal,
+      });
+      if (metadataCandidates.length > 0) {
+        const mergedById = new Map<string, LibraryTrackCandidate>();
+        for (const candidate of primaryLibraryCandidates) {
+          mergedById.set(candidate.persistentId, candidate);
+        }
+        for (const candidate of metadataCandidates) {
+          if (!mergedById.has(candidate.persistentId)) {
+            mergedById.set(candidate.persistentId, candidate);
+          }
+        }
+        libraryCandidates = [...mergedById.values()];
+      }
+    } catch {
+      // Keep primary library results if metadata fallback fails.
+    }
+  }
+
+  const rankedCandidates = rankLibraryCandidates({
+    candidates: libraryCandidates,
+    query,
+    title: title || query,
+    artist: artist || "",
+    enforceTitleMatch,
+    enforceArtistMatch,
+  });
+  const playlistQueries = buildPlaylistQueries({
+    query,
+    title,
+    artist,
+    rawQuery,
+  });
+  let playlistCandidates: LibraryPlaylistCandidate[] = [];
+  try {
+    playlistCandidates = await searchLibraryPlaylists(playlistQueries, context.signal);
+  } catch {
+    playlistCandidates = [];
+  }
+  const rankedPlaylists = rankPlaylistCandidates({
+    candidates: playlistCandidates,
+    query,
+    rawQuery,
+    playlistRequested,
+  });
+
+  const tryPlayTopPlaylist = async () => {
+    for (const entry of rankedPlaylists.slice(0, 3)) {
+      const playlistPlayback = await playLibraryPlaylistByPersistentId(
+        entry.candidate.persistentId,
+        context.signal,
+      );
+      if (!playlistPlayback.playing) {
+        continue;
+      }
+      return {
+        playing: true,
+        matched: true,
+        query: rawQuery || query || null,
+        playlistName: playlistPlayback.playlistName,
+        title: playlistPlayback.title,
+        artist: playlistPlayback.artist,
+        album: playlistPlayback.album,
+        source: "library_playlist",
+      };
+    }
+    return null;
+  };
+
+  const preferPlaylistByScore =
+    rankedPlaylists.length > 0 &&
+    !title &&
+    !artist &&
+    (rankedPlaylists[0]?.score ?? 0) >= 140;
+  const shouldPreferPlaylist = playlistRequested || preferPlaylistByScore;
+  if (shouldPreferPlaylist && rankedPlaylists.length > 0) {
+    const playlistPlayback = await tryPlayTopPlaylist();
+    if (playlistPlayback) {
+      return playlistPlayback;
+    }
+    if (playlistRequested) {
+      return {
+        playing: false,
+        query: rawQuery || query || null,
+        title: null,
+        artist: null,
+        playlistName: rankedPlaylists[0]?.candidate.name ?? null,
+        reason:
+          rankedPlaylists[0]?.candidate.name
+            ? `Found playlist "${rankedPlaylists[0].candidate.name}" in your Music library, but playback did not start.`
+            : "No matching playlist could be started from your Music library.",
+      };
+    }
+  }
+  const requestedTitleForMatch = title || query;
+  const requestedArtistForMatch = artist || "";
+
+  if (rankedCandidates.length === 0) {
+    if (!enforceTitleMatch && !enforceArtistMatch && rankedPlaylists.length > 0) {
+      const playlistPlayback = await tryPlayTopPlaylist();
+      if (playlistPlayback) {
+        return playlistPlayback;
+      }
+    }
+    return {
+      playing: false,
+      query: rawQuery || query || null,
+      title: title || null,
+      artist: artist || null,
+      reason:
+        playlistRequested || (!enforceTitleMatch && !enforceArtistMatch)
+          ? "No matching track or playlist was found in your Music library."
+          : "No matching track was found in your Music library.",
+    };
+  }
+
+  let nearestMatch: {
+    title: string | null;
+    artist: string | null;
+    album: string | null;
+  } | null = null;
+
+  for (const entry of rankedCandidates.slice(0, MAX_PLAYBACK_ATTEMPTS)) {
+    const playback = await playLibraryTrackByPersistentId(
+      entry.candidate.persistentId,
+      context.signal,
+    );
+    if (!playback.playing) {
+      continue;
+    }
+
+    const resolvedTitle = playback.title || entry.candidate.title;
+    const resolvedArtist = playback.artist || entry.candidate.artist;
+    const resolvedAlbum = playback.album || entry.candidate.album || null;
+
+    const isMatch = matchesRequestedTrack({
+      nowTitle: resolvedTitle,
+      nowArtist: resolvedArtist,
+      requestedTitle: requestedTitleForMatch,
+      requestedArtist: requestedArtistForMatch,
+      enforceTitleMatch,
+      enforceArtistMatch,
+    });
+
+    if (isMatch) {
+      return {
+        playing: true,
+        matched: true,
+        query: rawQuery || query || null,
+        title: resolvedTitle || null,
+        artist: resolvedArtist || null,
+        album: resolvedAlbum,
+      };
+    }
+
+    nearestMatch = {
+      title: resolvedTitle || null,
+      artist: resolvedArtist || null,
+      album: resolvedAlbum,
+    };
+  }
+
+  if (nearestMatch) {
+    if (enforceTitleMatch || enforceArtistMatch) {
+      return {
+        playing: false,
+        matched: false,
+        query: rawQuery || query || null,
+        title: title || null,
+        artist: artist || null,
+        matchedTitle: nearestMatch.title,
+        matchedArtist: nearestMatch.artist,
+        matchedAlbum: nearestMatch.album,
+        reason: "A nearby track played, but it did not match the requested song.",
+      };
+    }
+    return {
+      playing: true,
+      matched: false,
+      query: rawQuery || query || null,
+      title: nearestMatch.title,
+      artist: nearestMatch.artist,
+      album: nearestMatch.album,
+      reason: "Playback started with a nearby match.",
+    };
+  }
+
+  return {
+    playing: false,
+    query: rawQuery || query || null,
+    title: title || null,
+    artist: artist || null,
+    reason: "No matching track started playback.",
+  };
+}
+
+async function runMusicCommand(action: "pause" | "next" | "previous", context: ToolExecutionContext) {
+  ensureMacOS("Music automation");
+  if (context.localTools.dryRun) {
+    return { dryRun: true, action: `music_${action}` };
+  }
+
+  const script =
+    action === "pause"
+      ? 'tell application "Music" to pause'
+      : action === "next"
+        ? 'tell application "Music" to next track'
+        : 'tell application "Music" to previous track';
+  await runAppleScript(script, [], context.signal);
+  return { ok: true, action: `music_${action}` };
+}
+
+async function runMusicSetVolume(input: unknown, context: ToolExecutionContext) {
+  ensureMacOS("Volume automation");
+  const payload = asObject(input) as MusicSetVolumeInput;
+  const level = Math.max(0, Math.min(100, Math.round(asNumber(payload.level, "level"))));
+  const target = payload.target === "music" ? "music" : "system";
+
+  if (context.localTools.dryRun) {
+    return { dryRun: true, action: "music_set_volume", target, level };
+  }
+
+  const script =
+    target === "music"
+      ? `tell application "Music" to set sound volume to ${level}`
+      : `set volume output volume ${level}`;
+  await runAppleScript(script, [], context.signal);
+  return { target, level };
+}
+
+async function runMusicNowPlaying(_: unknown, context: ToolExecutionContext) {
+  ensureMacOS("Music automation");
+  const script =
+    'tell application "Music"\n' +
+    "if player state is stopped then return \"stopped\"\n" +
+    'set tName to name of current track\n' +
+    'set tArtist to artist of current track\n' +
+    'set tAlbum to album of current track\n' +
+    'set pState to player state as text\n' +
+    'return tName & tab & tArtist & tab & tAlbum & tab & pState\n' +
+    "end tell";
+  const output = await runAppleScript(script, [], context.signal);
+  if (output === "stopped") {
+    return { state: "stopped" };
+  }
+  const [title, artist, album, state] = output.split("\t");
+  return { state, title, artist, album };
+}
+
+export const musicTools: ToolDefinition[] = [
+  {
+    name: "music_play",
+    description: "Play Apple Music or resume playback.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        title: { type: "string" },
+        artist: { type: "string" },
+        source: { type: "string", enum: ["apple_music", "local_library"] },
+      },
+      additionalProperties: false,
+    },
+    risk: "app",
+    execute: runMusicPlay,
+  },
+  {
+    name: "music_pause",
+    description: "Pause Apple Music playback.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    risk: "app",
+    execute: async (_input, context) => runMusicCommand("pause", context),
+  },
+  {
+    name: "music_next",
+    description: "Skip to next track in Apple Music.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    risk: "app",
+    execute: async (_input, context) => runMusicCommand("next", context),
+  },
+  {
+    name: "music_previous",
+    description: "Go to previous track in Apple Music.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    risk: "app",
+    execute: async (_input, context) => runMusicCommand("previous", context),
+  },
+  {
+    name: "music_set_volume",
+    description: "Set system or Music app volume level.",
+    inputSchema: {
+      type: "object",
+      required: ["level"],
+      properties: {
+        level: { type: "number" },
+        target: { type: "string", enum: ["system", "music"] },
+      },
+      additionalProperties: false,
+    },
+    risk: "system",
+    execute: runMusicSetVolume,
+  },
+  {
+    name: "music_get_now_playing",
+    description: "Get currently playing track metadata.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    risk: "read",
+    execute: runMusicNowPlaying,
+  },
+];