@audiofool/moondog 0.3.0-beta.7 → 0.3.0-beta.8

package/src/runtime/pi/agent-runtime.mjs

@@ -183,6 +183,7 @@ function agentCapabilityAllowed(descriptor) {
     (descriptor.capability_id.startsWith("netease.") &&
       spotifyCapabilityEffects.has(descriptor.effect)) ||
     (descriptor.capability_id === "music.preview.play" && descriptor.effect === "play_preview") ||
+    (descriptor.capability_id === "collection.play" && descriptor.effect === "play_library") ||
     (["music.generate.local", "music.generate.replay", "music.generate.stream", "music.generate.stream.stop"].includes(descriptor.capability_id) &&
       descriptor.effect === "generate_local")
   );
@@ -3055,7 +3056,8 @@ function safeDomainFailure(error) {
   }
   const details = spotifyFailureDetails(error);
   const evidence = [details.status ? `HTTP ${details.status}` : "", details.reason].filter(Boolean);
-  return new Error(`${code}: ${message}${evidence.length ? ` (${evidence.join("; ")})` : ""}${details.not_sent ? " No Spotify write was dispatched for this attempt. Correct the arguments using retained host references; this is not an uncertain external effect." : ""}`);
+  // The status is for the model's diagnosis; labelled so, it is not copied into a reply.
+  return new Error(`${code}: ${message}${evidence.length ? ` [diagnosis only, never for the listener: ${evidence.join("; ")}]` : ""}${details.not_sent ? " No Spotify write was dispatched for this attempt. Correct the arguments using retained host references; this is not an uncertain external effect." : ""}`);
 }
 
 function spotifyFailureDetails(error) {
@@ -3487,7 +3489,7 @@ function projectSpotifyQueuePlan(value) {
     result.stopped = projectQueueTrackList([value.stopped], "spotify_queue_stopped")[0];
     if (value.failure) result.failure = { action: "playback.queue.add", ...spotifyFailureDetails(value.failure) };
   }
-  for (const field of ["skipped_duplicate_count", "skipped_avoided_count", "skipped_known_count", "skipped_uncertain_count", "not_added_count"]) {
+  for (const field of ["skipped_duplicate_count", "skipped_avoided_count", "skipped_known_count", "skipped_uncertain_count", "skipped_unavailable_count", "not_added_count"]) {
     if (value[field] !== undefined) result[field] = safeNonnegativeInteger(value[field], field);
   }
   if (["queue.similar", "queue.batch"].includes(value.action)) {
@@ -6606,6 +6608,93 @@ function createToolFactories(
         ),
       }),
     ],
+    [
+      "collection.list",
+      (descriptor) => ({
+        name: descriptor.tool_name,
+        label: descriptor.label,
+        description:
+          "Find playlists in the listener's own library on this Mac by words of their name, or list the newest ones without words. Saved is the built-in playlist of single songs and made tracks they kept. Each playlist says how many entries it holds and how many of them Moondog made. With playlist_id, it reads that playlist's entries in order.",
+        parameters: Type.Object(
+          {
+            query: Type.Optional(Type.String({ maxLength: 120 })),
+            playlist_id: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+          },
+          { additionalProperties: false },
+        ),
+        execute: executeDomain(
+          async (_toolCallId, parameters) => {
+            if (parameters.playlist_id) {
+              const playlist = await application.libraryPlaylist(parameters.playlist_id);
+              if (!playlist) throw Object.assign(new Error("That playlist is not in the library."), { code: "library_playlist_not_found" });
+              return { playlist: { id: playlist.id, name: playlist.saved ? "Saved" : playlist.name, origin: playlist.origin,
+                entries: playlist.entries.slice(0, 60).map((entry) => ({ title: entry.title, artist: entry.artist_credit, ...(entry.kind === "made" ? { made_by_moondog: true } : {}) })),
+                total: playlist.entries.length } };
+            }
+            return { playlists: application.findLibraryPlaylists(parameters.query ?? "") };
+          },
+          (value) => structuredClone(value),
+        ),
+      }),
+    ],
+    [
+      "collection.save",
+      (descriptor) => ({
+        name: descriptor.tool_name,
+        label: descriptor.label,
+        description:
+          "Keep music in the listener's own library on this Mac, only when they ask to save, keep, like or collect it. from now_playing keeps the song or made track playing now; from queue keeps it and what plays after it (the queue, or the rest of the playlist it plays from). Or give songs by title and artist, or made_track_id for a track Moondog made (product.made_tracks). With no playlist it goes in Saved; playlist_id adds to one of their playlists (from moondog_collection_list); playlist_name makes a new playlist with that name, in the listener's language. Saved holds each song once; already says how many were there.",
+        parameters: Type.Object(
+          {
+            from: Type.Optional(Type.Union([Type.Literal("now_playing"), Type.Literal("queue")])),
+            songs: Type.Optional(Type.Array(Type.Object({
+              title: Type.String({ minLength: 1, maxLength: 200 }),
+              artist: Type.String({ minLength: 1, maxLength: 200 }),
+              album: Type.Optional(Type.String({ maxLength: 200 })),
+            }, { additionalProperties: false }), { minItems: 1, maxItems: 50 })),
+            made_track_id: Type.Optional(Type.String({ minLength: 36, maxLength: 36 })),
+            playlist_id: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+            playlist_name: Type.Optional(Type.String({ minLength: 1, maxLength: 120 })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
+        execute: executeDomain(
+          async (_toolCallId, parameters, signal) => application.saveToLibrary({
+            from: parameters.from, songs: parameters.songs, madeTrackId: parameters.made_track_id,
+            playlistId: parameters.playlist_id, playlistName: parameters.playlist_name,
+          }, { by: "listener", signal }),
+          (value) => ({
+            playlist: { id: cleanOutputText(value.playlist?.id, 128, "playlist_id"), name: cleanOutputText(value.playlist?.name, 120, "playlist_name"),
+              ...(value.playlist?.created ? { created: true } : {}) },
+            added: Number(value.added) || 0,
+            already: Number(value.already) || 0,
+            titles: (value.titles ?? []).slice(0, 50).map((title) => cleanOutputText(title, 200, "title")),
+          }),
+        ),
+      }),
+    ],
+    [
+      "collection.play",
+      (descriptor) => ({
+        name: descriptor.tool_name,
+        label: descriptor.label,
+        description:
+          "Play a playlist from the listener's own library, by its id from moondog_collection_list, on the music service they chose. It is the listener's own music, so say its name and let it play; don't describe it as Moondog's pick. With Apple Music, songs and Moondog's tracks play in one queue in Moondog's player. With Spotify or NetEase its songs play there, and left_out_made says how many of Moondog's tracks in it could not play there. not_found counts songs no service found.",
+        parameters: Type.Object(
+          {
+            playlist_id: Type.String({ minLength: 1, maxLength: 128 }),
+            shuffle: Type.Optional(Type.Boolean()),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
+        execute: executeDomain(
+          async (_toolCallId, parameters, signal) => application.playLibrary({ playlistId: parameters.playlist_id, shuffle: parameters.shuffle === true }, { signal }),
+          (value) => structuredClone(value),
+        ),
+      }),
+    ],
     [
       "playlist.plan",
       (descriptor) => ({
@@ -6823,6 +6912,7 @@ Public web research rules:
 
 Grounding and evidence rules:
 - Before naming or selecting tracks as present in the user's library, call moondog_library_search.
+- The listener's collection in Moondog (Saved and their own playlists, which can hold songs and tracks Moondog made) is separate from their imported library and from Spotify. When they ask to save, keep, collect or like music (收藏, 存下来) without naming Spotify, use moondog_collection_save; use moondog_spotify_library_save only when they name Spotify or Liked Songs. To play one of their playlists, find it with moondog_collection_list and play it with moondog_collection_play.
 - When personalization matters, call moondog_profile_summary instead of assuming a profile.
 - Before saying how often, when, or whether the listener played something, check the listening coverage. Plays inside a gap, outside every source's span, or after recent_plays_checked_at are unknown, not zero. When a gap could hold the plays in question, lead with that boundary, for example "I have no records from August 30 to October 21", and do not conclude that the listener rarely plays it or only just found it.
 - The saved reading is enduring taste up to its listening date. Recent attention is the present: stored plays from the last four weeks, and Spotify's four-week top artists, which count listening on every device, including plays Moondog never stored and songs Moondog itself played or queued; stored plays count those apart as moondog_started_plays. When they disagree about what the listener plays lately, trust recent attention, and say which one you read.
@@ -7250,8 +7340,11 @@ function mergedQueueReceipt(plan, singles) {
   // A batch's mix line does not cover the single adds beside it.
   const { mix: _mix, ...base } = plan ?? { provider: "spotify", action: "playback.queue.add", state: "accepted", queued: [], unmatched: [], not_added: [] };
   const checks = [base.verification, ...singles.map(receipt => receipt.verification)].filter(Boolean);
+  const queued = [...base.queued, ...targets];
   return { ...base, state: ["no_candidates", "no_playback"].includes(base.state) ? "accepted" : base.state,
-    queued: [...base.queued, ...targets],
+    queued,
+    // Single adds that filled a short batch count against its shortfall too.
+    ...(Number.isInteger(base.requested) ? { shortfall: Math.max(0, base.requested - queued.length) } : {}),
     ...(base.device ?? singles.find(receipt => receipt.device)?.device ? { device: base.device ?? singles.find(receipt => receipt.device).device } : {}),
     ...(base.started_playback ? {} : singles[0]?.started_playback ? { started_playback: targets[0] } : {}),
     ...(checks.length ? { verification: { checked: checks.every(check => check.checked),
@@ -7915,9 +8008,21 @@ export class PiAgentRuntime {
           };
         }
         const state = this.activePromptState;
-        if (state?.spotifyQueuePlan?.action === "queue.batch" && state.spotifyQueuePlan.queued.length > 0 &&
+        const batch = state?.spotifyQueuePlan?.action === "queue.batch" && state.spotifyQueuePlan.queued.length > 0 ? state.spotifyQueuePlan : null;
+        // A batch that came up short may still be filled by single adds of other songs, one per
+        // missing song; a song the batch queued is never added again.
+        // The application counts the fills and checks each against the queue; this only lets one through.
+        const shortfall = batch ? Math.max(0, (batch.requested ?? 0) - batch.queued.length) : 0;
+        const fillRef = toolCall.arguments?.item_ref_id ?? toolCall.arguments?.track_ref_id;
+        const fillItem = batch && descriptor.capability_id === "spotify.queue.add" && typeof fillRef === "string" && !toolCall.arguments?.pending_plan
+          ? application.spotifyHostReadItems?.().find((item) => item.item_ref_id === fillRef) : null;
+        // Which song is a duplicate is the application's call, by title and artist, against the queue too.
+        const fillsBatch = Boolean(fillItem?.type === "track" && shortfall > 0);
+        if (batch && !fillsBatch &&
             ["spotify.player.control", "spotify.queue.add", "spotify.queue.batch", "spotify.device.transfer", "spotify.queue.similar"].includes(descriptor.capability_id)) {
-          return { block: true, reason: "The requested queue batch already has a receipt. Do not add, replay or replace its writes in this turn." };
+          return { block: true, reason: shortfall > 0 && descriptor.capability_id === "spotify.queue.add"
+            ? "That song is already in the batch's receipt, or its reference is unknown. Add only a missing song by its item_ref_id."
+            : "The requested queue batch already has a receipt. Do not add, replay or replace its writes in this turn." };
         }
         const listeningContext = application.spotifyPlaybackContextStatus?.();
         if (listeningContext?.queue_request && state) {
@@ -7927,7 +8032,7 @@ export class PiAgentRuntime {
         if (listeningContext?.queue_request?.clarification_only && descriptor.effect === "write_external") {
           return { block: true, reason: "The earlier queue already has an accepted, failed or uncertain receipt. A clarification about queue versus playlist must not replay it. Report the existing receipt." };
         }
-        if (listeningContext?.queue_request?.requested > 1 && descriptor.capability_id === "spotify.queue.add" && !toolCall.arguments?.pending_plan) {
+        if (listeningContext?.queue_request?.requested > 1 && descriptor.capability_id === "spotify.queue.add" && !toolCall.arguments?.pending_plan && !fillsBatch) {
           return { block: true, reason: "Use moondog_spotify_queue_batch for this multi-song queue request so Avoid, deduplication, count and partial receipts are preserved." };
         }
         // A refused or uncertain write ends the turn's playback writes; the model explains it.

package/src/runtime/pi/model-transport.mjs

@@ -89,11 +89,27 @@ function replayableBody(input, init) {
     ArrayBuffer.isView(body) || body instanceof URLSearchParams || body instanceof Blob;
 }
 
+// Statuses that say the provider is busy right now, not that the request is wrong.
+const overloadStatuses = new Set([502, 503, 504, 529]);
+const maximumOverloadRetries = 3;
+
+// How long to wait before sending an overloaded request again, or null to return the response.
+// A 429 is retried only when the provider asks for a short wait; a long one is usually a quota.
+function overloadRetryDelay(response, retries) {
+  if (!response || typeof response.status !== "number") return null;
+  const value = response.headers?.get?.("retry-after");
+  const header = value === null || value === undefined || value === "" ? NaN : Number(value);
+  const asked = Number.isFinite(header) && header >= 0 ? header * 1000 : null;
+  if (response.status === 429) return asked !== null && asked <= 10_000 ? asked : null;
+  if (!overloadStatuses.has(response.status)) return null;
+  return Math.min(asked ?? 1000 * 2 ** retries, 10_000);
+}
+
 async function retryDelay(milliseconds, signal) {
   await delay(milliseconds, undefined, { signal });
 }
 
-/** Recover only rejected model HTTP fetches, before a Response or stream exists. */
+/** Recover rejected model HTTP fetches, and overloaded answers, before a stream exists. */
 export function createModelFetch({
   provider,
   fetchImpl = globalThis.fetch,
@@ -104,11 +120,24 @@ export function createModelFetch({
   return async (input, init) => {
     const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
     const canReplay = replayableBody(input, init);
-    for (let attempt = 0; ; attempt += 1) {
+    // Connection failures and overloaded answers each have their own small budget.
+    let overloadAttempts = 0;
+    let attempt = 0;
+    for (;;) {
       signal?.throwIfAborted();
       try {
-        // Status codes and response-body errors remain Pi's responsibility.
-        return await fetchImpl(input, init);
+        const response = await fetchImpl(input, init);
+        // A provider that is overloaded answers before it produces anything, so the same request
+        // is sent again after a short wait. Other status codes and body errors stay Pi's.
+        const retryAfter = overloadRetryDelay(response, overloadAttempts);
+        if (canReplay && retryAfter !== null && overloadAttempts < maximumOverloadRetries) {
+          overloadAttempts += 1;
+          await response.body?.cancel().catch(() => {});
+          onRetry?.({ attempt: overloadAttempts, maxRetries: maximumOverloadRetries, status: response.status });
+          await wait(retryAfter, signal);
+          continue;
+        }
+        return response;
       } catch (cause) {
         if (signal?.aborted || cause?.name === "AbortError") throw cause;
         const failure = connectionFailure(cause);
@@ -116,6 +145,7 @@ export function createModelFetch({
         if (canReplay && failure.retryable && attempt < maximumRetries) {
           onRetry?.({ attempt: attempt + 1, maxRetries: maximumRetries });
           await wait(250 * 2 ** attempt, signal);
+          attempt += 1;
           continue;
         }
         const error = createModelConnectionError({ provider, cause });

package/src/runtime/pi/tool-arguments.mjs

@@ -15,8 +15,12 @@ function passes(tool, args) {
   }
 }
 
+// A key that is no identifier ("/invoke", "invoke name=\"…\"") is a model's own tool-call markup
+// leaking into the arguments. No tool takes such a key, so it carries no meaning to refuse.
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+
 function withoutEmpty(args) {
-  return Object.fromEntries(Object.entries(args).filter(([, value]) =>
+  return Object.fromEntries(Object.entries(args).filter(([key, value]) => IDENTIFIER.test(key) &&
     value !== null && value !== undefined && !(typeof value === "string" && !value.trim())));
 }
 

package/src/surfaces/cli/tui.mjs

@@ -125,6 +125,7 @@ const slashCommands = [
   { name: "endpoint", description: N_("Add a model service by its address") },
   { name: "web", description: N_("Look things up on public music sites") },
   { name: "service", description: N_("Choose where Moondog plays music") },
+  { name: "library", description: N_("Your saved songs and playlists") },
   { name: "generation", description: N_("Let Moondog make music on this Mac") },
   { name: "onair", description: N_("Go on air: Moondog keeps making music from your taste") },
   { name: "spotify", description: N_("Connect and control Spotify") },
@@ -250,7 +251,8 @@ export async function runMoondogTui({
   // /onair needs both: the room's own player and music making here.
   const onAirControls = previewControls && typeof generation?.save === "function";
   const commands = slashCommands.filter(({ name }) => (previewControls || !["skip", "stop"].includes(name)) &&
-    (name !== "generation" || typeof generation?.save === "function") && (name !== "onair" || onAirControls));
+    (name !== "generation" || typeof generation?.save === "function") && (name !== "onair" || onAirControls) &&
+    (name !== "library" || application.libraryReady?.() === true));
   const localizedCommands = commands.map(({ name, description }) => ({ name, get description() { return tr.marked(description); } }));
   let activeRuntime = runtime;
   application.startNewSession?.("tui_start");
@@ -1037,6 +1039,59 @@ export async function runMoondogTui({
     generationFooter(status);
   };
 
+  // /library lists Saved and the listener's folders and playlists, plays one by name, or keeps the song
+  // playing now, in Saved or in a playlist by name (made when there is none). The window shares this library.
+  const manageLibrary = async (args) => {
+    if (!application.libraryReady?.()) throw new Error(tr("The library isn't available here."));
+    const [action, ...rest] = args;
+    const words = rest.join(" ").trim();
+    const nameOf = (playlist) => (playlist.saved ? tr("Saved") : playlist.name);
+    if (!action) {
+      const { folders, playlists } = application.libraryView();
+      const count = (playlist) => tr.n(playlist.count, "{count} song", "{count} songs");
+      const lines = [];
+      const saved = playlists.find((playlist) => playlist.saved);
+      if (saved) lines.push(`- **${nameOf(saved)}** · ${count(saved)}`);
+      const walk = (parentId, depth) => {
+        const nodes = [...folders.filter((folder) => folder.parentId === parentId).map((node) => ["folder", node]),
+          ...playlists.filter((playlist) => !playlist.saved && playlist.folderId === parentId).map((node) => ["playlist", node])]
+          .sort((a, b) => a[1].position - b[1].position);
+        for (const [kind, node] of nodes) {
+          const indent = "  ".repeat(depth);
+          if (kind === "folder") { lines.push(`${indent}- ${node.name}/`); walk(node.id, depth + 1); }
+          else lines.push(`${indent}- **${node.name}** · ${count(node)}`);
+        }
+      };
+      walk(null, 0);
+      addMoondogMessage(`${lines.join("\n")}\n\n${tr("Play one with `/library play <name>`, or keep the song playing now with `/library save`.")}`);
+      return;
+    }
+    if (action === "play") {
+      const [playlist] = application.findLibraryPlaylists(words);
+      if (!playlist || !words) throw new Error(tr("No playlist is called “{name}”.", { name: words }));
+      const played = await application.playLibrary({ playlistId: playlist.id });
+      if (played.state !== "playing") {
+        addMoondogMessage(played.state === "empty" ? tr("{name} has nothing in it yet.", { name: nameOf(playlist) }) : tr("None of its songs could be found."));
+        return;
+      }
+      addMoondogMessage([tr("Playing {name}.", { name: nameOf(playlist) }),
+        played.left_out_made ? tr("Moondog's tracks were left out. They play with Apple Music chosen.") : "",
+        played.not_found ? tr("Some songs couldn't be found.") : ""].filter(Boolean).join(" "));
+      setFooter(tr("Playing {name}.", { name: nameOf(playlist) }), success);
+      return;
+    }
+    if (action === "save") {
+      const target = words ? application.findLibraryPlaylists(words).find((playlist) => playlist.name.toLocaleLowerCase() === words.toLocaleLowerCase() || (playlist.saved && /^saved$/iu.test(words))) : null;
+      const saved = await application.saveToLibrary({ from: "now_playing", ...(target ? { playlistId: target.id } : words ? { playlistName: words } : {}) });
+      const where = saved.playlist.saved ? tr("Saved") : saved.playlist.name;
+      const text = !saved.added ? tr("Already in {name}.", { name: where }) : saved.playlist.saved ? tr("Saved.") : tr("Saved to {name}.", { name: where });
+      addMoondogMessage(text);
+      setFooter(text, success);
+      return;
+    }
+    throw new Error(tr("Use /library, /library play <name>, or /library save [playlist]."));
+  };
+
   const removeLifecycleListeners = () => {
     signalTarget.removeListener("SIGTERM", handleSigterm);
     signalTarget.removeListener("SIGHUP", handleSighup);
@@ -2499,6 +2554,10 @@ export async function runMoondogTui({
       await manageGeneration(args);
       return;
     }
+    if (command === "library") {
+      await manageLibrary(args);
+      return;
+    }
     if (command === "spotify") {
       await runSpotifyCommand(args);
       return;