@audiofool/moondog 0.3.0-beta.1 → 0.3.0-beta.11

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">Moondog</h1>
 
-<p align="center">Source candidate 0.3.0-beta.1</p>
+<p align="center">Source candidate 0.3.0-beta.11</p>
 
 <p align="center"><strong>A listening room that shows its work.</strong></p>
 
@@ -44,7 +44,8 @@ See [updating and release channels](docs/UPDATES.md), including the one-time upg
 
 [Moondog for Mac](app/README.md) is a native window on the same core as the terminal room.
 It shares your profile, settings, sign-ins, and conversations with `moondog`, and draws its own conversation, now playing, and up next.
-Run it from this checkout with `cd app && npm ci && npm start`.
+Download the notarized build for Apple silicon from the [project page](https://moondog.audiofool.ai), or run it from this checkout with `cd app && npm ci && npm start`.
+It updates itself, on a Stable or Beta channel you choose in Settings.
 
 The [project page](https://moondog.audiofool.ai) plays a short scene in this window, in a browser, with a made-up listener ([how](site/README.md)).
 
@@ -147,11 +148,17 @@ OpenAI takes your ChatGPT subscription or an API key.
 In the Mac app, any service that speaks OpenAI's or Anthropic's API can be added as an endpoint by its address, and `/endpoint` does it in the terminal.
 You can switch models in the middle of a conversation.
 The [model setup guide](docs/TERMINAL_GUIDE.md#enable-agent-conversation) lists each provider and the environment variable it reads.
+`/model roles` shows the models and services behind side tasks: a vision model for images, and the web search service.
+Moondog takes images too: an image path in your message in the terminal, or a pasted or dropped image in the Mac app.
+You can also change settings in your own words, such as which model answers or the language it replies in.
 
 While an answer is on the way, each step appears in the conversation as it starts.
 The steps stay above the reply, with a count of what finished, what failed, and what was not confirmed.
 The agent can use musical knowledge and web research to find candidates, then verify the recordings on Spotify before playing or queueing them.
 Without Spotify, it plays 30-second Apple Music previews from the terminal instead, each next to a link to the full song.
+With NetEase Music, it plays whole songs through NetEase's own `ncm-cli`.
+In the Mac app, Apple Music plays whole songs with a subscription.
+`/service` chooses where Moondog plays.
 It also sees what you already play: the song and playlist in the Music app on a Mac, or on Spotify's active device, so “more like this playlist” needs no names.
 macOS asks once before Moondog may read the Music app.
 For example, “Pon doce de salsa clásica a la cola” asks it to add up to twelve verified songs directly; your history guides the choice without limiting it to your library.
@@ -164,13 +171,28 @@ Songs Moondog chose for you do not count as your own taste.
 | A model through Pi | Conversation, discovery, and playlists built together. |
 | A web search service | `/web` lookups with links to their sources, through DeepSeek (`/auth deepseek`, which also reads pages), Brave Search (`/auth brave`), or your own signed-in Codex CLI. |
 | Spotify sign-in | Playback, and private playlists made only when you ask. |
+| NetEase Music | Whole songs through its own `ncm-cli`, for listeners in mainland China. |
 
 Your profile never touches the network.
 The agent talks only to the services you set up.
 `/web` sends the question or the link you give it, and nothing from your profile, history, or files.
+An image you attach goes to the model that reads it.
 A Spotify ZIP does not need a Spotify sign-in.
 Read the [connection and data details](docs/TERMINAL_GUIDE.md) before you connect anything.
 
+## Your library
+
+`/library` keeps songs and the tracks Moondog made side by side: Saved, then your playlists.
+`/library save` keeps what is playing, and `/library play Night drive` plays a playlist on the service you chose.
+`/library import <link>` copies a Spotify, Apple Music, NetEase Music or QQ Music playlist into it.
+A playlist you made on Spotify also shapes your taste; for any other one, you decide.
+
+## Music it makes
+
+On an Apple silicon Mac, Moondog can make instrumental tracks offline with Stable Audio 3, powered by Stability AI.
+`/generation download medium` sets it up after you agree to its licenses, and `/generation on` turns it on.
+Ask for a track, or type `/onair` and Moondog keeps making music from your taste until you stop it.
+
 ## Getting around
 
 | Command or key | What it does |
@@ -186,7 +208,10 @@ Read the [connection and data details](docs/TERMINAL_GUIDE.md) before you connec
 | Enter while Moondog is working | Queue the next message. It sends when this one finishes. |
 | `/resume`, `/new` | Pick up a saved conversation, or start a fresh one. |
 | `/home` | Back to the sleeve, without clearing the conversation. |
-| `/skip`, `/stop` | Skip to the next song preview, or stop the previews. |
+| `/skip`, `/stop` | Skip to the next song preview or stream track, or stop them. |
+| `/library` | Your saved songs and playlists. |
+| `/onair` | Go on air, or come off it. |
+| `/rewind`, `/branch` | Change an earlier message, or go on in a new conversation. |
 | `/lyrics` | See which line is on the sleeve, and which song it came from. |
 | `/theme paper` | Black ink on white. |
 | `/theme charcoal` | Moonlight on a black sky. |
@@ -203,6 +228,7 @@ Your profile, and anything Moondog remembers, carry over.
 - [Product charter](docs/PRODUCT_CHARTER.md) and [public roadmap](docs/ROADMAP.md): where Moondog is headed, and what it will not do.
 - [Voice](docs/VOICE.md): how Moondog talks, and where Pink Floyd shows up.
 - [The listening loop](docs/LISTENING_LOOP.md): how the agent keeps your choices, your recent listening, and its own picks apart.
+- [The agent harness](docs/AGENT_HARNESS.md): how the tools keep the model's part small, so every supported model can play what you ask, and how each model is measured.
 - [Runtime architecture](docs/ADR_0001_AGENT_RUNTIME_AND_CLI.md) and [data contracts](contracts/README.md): how the pieces fit together.
 - [Contribution guide](CONTRIBUTING.md): local setup, checks, and how private data is kept out.
 - [Release status](docs/PUBLIC_RELEASE_READINESS.md): what is published, and what the checks cover.
@@ -212,4 +238,4 @@ Your profile, and anything Moondog remembers, carry over.
 
 Moondog is open source under the [Apache License 2.0](LICENSE).
 Copyright 2026 Audiofool.
-Music making runs Stable Audio 3, which you install yourself; [NOTICE](NOTICE) holds its attribution, and [licenses/](licenses/stability-ai-community-license.md) holds the Stability AI Community License.
+Music making runs Stable Audio 3, which Moondog downloads from Stability AI when you ask, or your own install; [NOTICE](NOTICE) holds its attribution, and [licenses/](licenses/stability-ai-community-license.md) holds the Stability AI Community License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audiofool/moondog",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.11",
   "type": "module",
   "description": "Local-first personal AI music agent.",
   "license": "Apache-2.0",

package/scripts/moondog.mjs

@@ -7,6 +7,7 @@ import { runUpdateCommand } from "../src/surfaces/cli/update-command.mjs";
 
 import { MoondogApplication } from "../src/core/moondog-application.mjs";
 import { openLocalMemoryStore } from "../src/memory/local-memory-store.mjs";
+import { openLibraryStore } from "../src/core/library-store.mjs";
 import {
   openAppleProjectionDomainServices,
   resolveAppleMusicSubjectId,
@@ -32,8 +33,10 @@ import { runCatalogCommand } from "../src/surfaces/cli/catalog-command.mjs";
 import { runProfileCommand } from "../src/surfaces/cli/profile-command.mjs";
 import { runListenerProfileCommand, savedProfileActions } from "../src/surfaces/cli/listener-profile-command.mjs";
 import { createWebResearch } from "../src/integrations/web/web-research.mjs";
+import { runModelRolesCommand } from "../src/surfaces/cli/model-roles-command.mjs";
 import { runWebCommand } from "../src/surfaces/cli/web-command.mjs";
 import { openSpotifyConnection } from "../src/integrations/spotify/connection.mjs";
+import { preferredIdleDevice, thisComputerName } from "../src/integrations/spotify/service.mjs";
 import {
   openSpotifyResolutionCache,
 } from "../src/integrations/spotify/resolution-cache.mjs";
@@ -43,6 +46,7 @@ import {
 import { runSpotifyCommand } from "../src/surfaces/cli/spotify-command.mjs";
 import { runListenBrainzCommand } from "../src/surfaces/cli/listenbrainz-command.mjs";
 import { openListeningHistoryStore } from "../src/profile/listening-history-store.mjs";
+import { musicHash, prepareMusicBundle } from "../src/profile/music-import-bundle.mjs";
 import { commitSpotifyQuickImport, prepareHistoryImport, prepareSpotifyQuickImport } from "../src/profile/history-import.mjs";
 import { persistAppleLibraryImport, refreshAppleLibraryImport } from "../src/profile/apple-library-import.mjs";
 import { IMPORT_GUIDE_URLS } from "../src/surfaces/cli/import-guides.mjs";
@@ -54,6 +58,7 @@ import { createAppleMusicCatalog } from "../src/integrations/apple-music/catalog
 import { createTerminalPreviewPlayer } from "../src/integrations/apple-music/terminal-preview-player.mjs";
 import { createNeteasePlayer } from "../src/integrations/netease/ncm-cli-player.mjs";
 import { createAtmosphereStream, createLocalGenerator } from "../src/integrations/stable-audio/local-generator.mjs";
+import { createStableAudioSetup } from "../src/integrations/stable-audio/setup.mjs";
 import { createMusicAppPlayer } from "../src/integrations/apple-music/music-app.mjs";
 import {
   createOpenMusicSimilarity,
@@ -69,7 +74,8 @@ import {
   SPOTIFY_ARCHIVE_SET_MAXIMUM,
 } from "../src/profile/spotify-archive-taste.mjs";
 import { deriveArtistReleaseHintsFromSpotifyArchive } from "../src/profile/spotify-archive-catalog-hints.mjs";
-import { resolveListenerLocale, writeLanguagePreference } from "../src/i18n/preferences.mjs";
+import { createLanguageSelection, resolveListenerLocale, writeLanguagePreference } from "../src/i18n/preferences.mjs";
+import { createModelSwitch } from "../src/runtime/pi/model-switch.mjs";
 import { createPlaybackSelection, resolvePlaybackService, watchPlaybackPreference, writePlaybackPreference } from "../src/core/playback-preferences.mjs";
 import { createFirstRun } from "../src/core/first-run.mjs";
 
@@ -146,6 +152,28 @@ function parseArguments(argv) {
   };
 }
 
+// A playlist imported into the library adds its songs to the listener's taste evidence, as a kept playlist, the
+// same way a public playlist imported from the Import guide does. Its source names where it came from.
+const PLAYLIST_TASTE_SOURCES = { spotify: "spotify_playlist", apple_music: "apple_music_playlist", netease: "netease", qq_music: "qq_music" };
+async function addPlaylistToTaste(found) {
+  const provider = PLAYLIST_TASTE_SOURCES[found.provider];
+  if (!provider) throw new Error("This playlist's service can't shape the profile.");
+  const historyStore = await openListeningHistoryStore();
+  try {
+    const appleSubjectId = await optionalAppleMusicSubjectId();
+    const subjectId = historyStore.localSubjectId({ ...(appleSubjectId ? { preferredSubjectId: appleSubjectId } : {}), create: true });
+    const rows = found.tracks.map((track, index) => ({ id: track.id, title: track.title, artist: track.artist, ...(track.album ? { album: track.album } : {}),
+      playlistId: found.id, playlistName: found.name, position: index + 1, member: "playlist-link.json", listenerMade: found.owned === true }));
+    const bytes = Buffer.from(JSON.stringify({ provider, id: found.id, name: found.name, rows }));
+    const prepared = prepareMusicBundle({ provider, subjectId, capturedAt: new Date().toISOString(), rows, digest: musicHash(bytes), size: bytes.length,
+      members: ["playlist-link.json"], fileName: found.name,
+      scopeNote: "A playlist the listener imported into their library. It shows what they keep, not what they played." });
+    return historyStore.ingestImport(prepared.bundle);
+  } finally {
+    historyStore.close();
+  }
+}
+
 async function optionalAppleMusicSubjectId() {
   const source = await readAppleMusicSourceStatus();
   if (source.state === "missing") return null;
@@ -452,6 +480,76 @@ async function emitTasteprintArtifact(
   return result;
 }
 
+// While the terminal's stream runs, the Music app is read this often. Only a change from not playing
+// to playing ends the stream, and only in a read that began after the stream last changed and past its
+// start: the song the first track pauses keeps playing while that track is made.
+const STREAM_MUSIC_APP_MS = 5_000;
+function watchMusicAppForStream(stream, { musicApp, interval = STREAM_MUSIC_APP_MS }) {
+  if (musicApp?.available !== true) return () => {};
+  let timer = null;
+  let reading = false;
+  let playing = null;
+  let phase = null;
+  let changedAt = 0;
+  const read = async () => {
+    if (reading) return;
+    reading = true;
+    const began = Date.now();
+    try {
+      const now = await musicApp.nowPlaying().catch(() => null);
+      const view = stream.view();
+      if (!view || began <= changedAt) return;
+      const playingNow = now?.state === "playing";
+      if (playingNow && playing === false && view.phase !== "starting") stream.stop("other_music");
+      playing = playingNow;
+    } finally {
+      reading = false;
+    }
+  };
+  const unsubscribe = stream.subscribe(({ view }) => {
+    changedAt = Date.now();
+    // The first track just paused the Music app, so playing at a later read is news.
+    if (phase === "starting" && view && view.phase !== "starting") playing = false;
+    phase = view?.phase ?? null;
+    if (view && !timer) {
+      playing = null;
+      timer = setInterval(() => void read(), interval);
+      timer.unref?.();
+    } else if (!view && timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  });
+  return () => {
+    unsubscribe();
+    clearInterval(timer);
+    timer = null;
+  };
+}
+
+// Whether a /spotify command starts Spotify on this Mac: play on the device it resumes on (the active one,
+// or with none active the one it would pick), or a move onto this Mac with --play or while Spotify plays (a
+// move keeps playing what plays). A command its own checks refuse, or reads that fail, start nothing here.
+async function spotifyStartsHere(application, args, { signal } = {}) {
+  if (!application.spotifyReady?.()) return false;
+  // A trailing --json changes only how the result is written.
+  if (args.at(-1) === "--json") args = args.slice(0, -1);
+  const play = args[0] === "play" && args.length <= 2;
+  const transfer = args[0] === "transfer" && args.length >= 2 && args.length <= 3 && (args.length === 2 || args[2] === "--play");
+  if (!play && !transfer) return false;
+  const service = application.requireSpotifyService();
+  const [listed, player] = await Promise.all([service.devices({ signal }).catch(() => null), service.currentPlayer({ signal }).catch(() => null)]);
+  const devices = listed?.devices ?? [];
+  if (transfer) {
+    const device = devices.find((entry) => entry.id === args[1]);
+    const playing = player?.state === "available" && player.is_playing === true;
+    return Boolean(device) && application.spotifyOnThisMac(device) && (args[2] === "--play" || playing);
+  }
+  const active = player?.device?.is_active === true ? player.device : devices.find((device) => device.is_active === true);
+  const device = active ?? preferredIdleDevice(devices, { thisComputer: await thisComputerName() });
+  return Boolean(device) && application.spotifyOnThisMac(device);
+}
+
 async function main() {
   const updater = createApplicationUpdater();
   const argv = process.argv.slice(2);
@@ -830,6 +928,9 @@ async function main() {
 
   const domainState = await loadDomainServices();
   const memoryStore = await openLocalMemoryStore();
+  // The listener's library: Saved, their playlists and folders, on one file the terminal and the window share.
+  // A library that can't open leaves the rest of Moondog working, without it.
+  const libraryStore = await openLibraryStore().catch(() => null);
   const spotifyConnection = await loadSpotifyConnection();
   const musicCatalog = createAppleMusicCatalog();
   const artistIdentityResolver = createWikidataArtistResolver();
@@ -851,10 +952,14 @@ async function main() {
   const neteasePlayer = createNeteasePlayer();
   const playbackService = await resolvePlaybackService();
   if (playbackService === "netease") await neteasePlayer.check();
-  // Moondog makes music on this Mac with the listener's own Stable Audio 3 once they turn it on, in a
-  // room that can play what it makes. The terminal and the window each keep one generator, so each
-  // makes one track at a time; a choice saved on one side is checked again on the other.
-  const localGenerator = previewPlayer ? createLocalGenerator() : null;
+  // Moondog makes music on this Mac with Stable Audio 3 once the listener turns it on, in a room
+  // that can play what it makes: Moondog's own install, downloaded when they ask, or their folder.
+  // The terminal and the window each keep one generator, so each makes one track at a time; a
+  // choice saved on one side is checked again on the other.
+  const localGenerator = previewPlayer ? createLocalGenerator({ keeps: (id) => libraryStore?.holdsMade(id) === true }) : null;
+  const generationSetup = localGenerator ? createStableAudioSetup() : null;
+  // A model set up or removed, here or on the other side, is checked again.
+  const unwatchGenerationSetup = generationSetup?.subscribe(() => { void localGenerator.check().catch(() => {}); }) ?? (() => {});
   await localGenerator?.check();
   void localGenerator?.sweep().catch(() => {});
   const unwatchGeneration = localGenerator?.watch() ?? (() => {});
@@ -869,11 +974,20 @@ async function main() {
   const unobserveStream = atmosphereStream ? previewPlayer.subscribe?.((event) => atmosphereStream.observe(event)) : null;
   // Music making turned off, here or on the other surface, ends the stream.
   const unwatchStreamGeneration = atmosphereStream ? localGenerator.subscribe((status) => { if (status.state !== "ready") atmosphereStream.stop("generation_off"); }) : null;
+  // The window watches the Music app for its own stream; the terminal has no window, so while its
+  // stream runs it reads the Music app itself, and music the listener starts there ends the stream.
+  const unwatchStreamMusicApp = atmosphereStream && !host ? watchMusicAppForStream(atmosphereStream, { musicApp }) : null;
   const playbackSelection = createPlaybackSelection({ service: playbackService, save: writePlaybackPreference });
+  // A reply language the listener asks for in words is saved like the picker's and reaches every surface.
+  const languageSelection = createLanguageSelection({ save: (locale) => writeLanguagePreference(locale) });
+  // The listener's model menu, shared by the window, the terminal and a model asked for in words.
+  const modelSettings = createModelSettings({ environment: process.env });
+  const modelSwitch = createModelSwitch({ list: () => modelSettings.list() });
   // The terminal and the window each run this core on one playback.json. A service chosen on the
-  // other side reaches this side's picker and agents, and stops the previews this side plays.
+  // other side reaches this side's picker and agents, and stops the Apple Music songs this side plays.
+  // Moondog's stream is not a service: its made tracks play on.
   const unwatchPlayback = watchPlaybackPreference(playbackSelection, {
-    onChange: (service) => { if (service !== "apple_music") { atmosphereStream?.stop("service_change"); previewPlayer?.stop?.(); } },
+    onChange: (service) => { if (service !== "apple_music" && previewPlayer?.holdsCatalogSongs?.() !== false) previewPlayer?.stop?.(); },
   });
   // The main application and every conversation the window opens beside it are built from
   // this one list, so they cannot drift apart. Each passes in what may change after launch:
@@ -881,9 +995,11 @@ async function main() {
   // Spotify's four-week top artists, as the listening upkeep last read them.
   const spotifyTopArtists = { read_at: null, artists: [] };
   const applicationOptions = ({ domainServices, domainServicesError, spotifyConnection, locale, playbackService }) => ({
-    domainServices, domainServicesError, spotifyConnection, locale, playbackService, playbackSelection,
+    domainServices, domainServicesError, spotifyConnection, locale, playbackService, playbackSelection, languageSelection, modelSwitch,
     webResearch, memoryStore, musicCatalog, musicPreviewPlayer: previewPlayer, neteasePlayer, localGenerator, atmosphereStream, musicSimilarity, artistIdentityResolver,
-    spotifyTopArtists, musicApp,
+    spotifyTopArtists, musicApp, libraryStore,
+    // A playlist that shapes the taste reloads the profile services at once, so the evidence counts in this session.
+    playlistTaste: async (found) => { const receipt = await addPlaylistToTaste(found); replaceDomainServices(await loadDomainServices()); return receipt; },
   });
   const application = new MoondogApplication(applicationOptions({
     ...domainState, spotifyConnection, locale: await resolveListenerLocale(), playbackService,
@@ -1083,7 +1199,12 @@ async function main() {
         status: () => localGenerator.status(),
         check: () => localGenerator.check(),
         save: (settings) => localGenerator.save(settings),
+        // Uses an installed model of Moondog's own install.
+        use: async (model) => (generationSetup?.status()?.models?.[model]?.state === "ready"
+          ? localGenerator.save({ source: "managed", model }) : localGenerator.check()),
         subscribe: (listener) => localGenerator.subscribe(listener),
+        // Download, cancel and remove, shared by the window and the terminal.
+        setup: generationSetup,
       },
       // The room asks whether a Last.fm key is set, and saves one the listener pastes.
       lastfm: {
@@ -1113,12 +1234,16 @@ async function main() {
         return createConfiguredRuntime(target, process.env, { selection, toolTrace });
       },
       // The desktop window lists models and signs in here, with no terminal.
-      modelSettings: createModelSettings({ environment: process.env }),
+      modelSettings,
       // A model chosen or a sign-in made on the other surface. Model variables fix the model at
-      // launch, so a saved choice has nothing to change then.
-      watchModelSettings: (onChange) => (process.env.MOONDOG_PROVIDER !== undefined || process.env.MOONDOG_MODEL !== undefined
-        ? () => {}
-        : watchRuntimeSettings({ environment: process.env, onChange })),
+      // launch, so a saved choice has nothing to change then; a role chosen elsewhere still does.
+      watchModelSettings: (onChange) => {
+        const fixed = process.env.MOONDOG_PROVIDER !== undefined || process.env.MOONDOG_MODEL !== undefined;
+        return watchRuntimeSettings({ environment: process.env, onChange: (selection, changed) => {
+          if (changed === "roles") return void webResearch.refresh().then(() => onChange(selection, changed), () => {});
+          if (!fixed) onChange(selection, changed);
+        } });
+      },
       // The one-time music service and model setup, shared by the terminal and the window.
       firstRun: createFirstRun({ environment: process.env }),
       // A host with its own terminal streams takes the sign-in prompts. The
@@ -1144,6 +1269,7 @@ async function main() {
           }),
         }),
       runWeb: (args, options) => runWebCommand({ args, webResearch, ...options }),
+      runModelRoles: (args) => runModelRolesCommand({ args: args.map(String), modelSettings, webResearch }),
       runProfileAction: (args) => runProfileCommand({
         args,
         commandPrefix: "/profile",
@@ -1167,6 +1293,9 @@ async function main() {
         return json ? `\`\`\`json\n${output.trim()}\n\`\`\`` : output.trim();
       },
       runSpotify: async (args, { signal, stderr } = {}) => {
+        // /spotify play, and a move onto this Mac that plays there, start Spotify here: the other players go
+        // quiet first. A command its own checks will refuse, or a move to another device, quiets nothing.
+        if (await spotifyStartsHere(application, args, { signal })) await application.quietOtherPlayers("spotify", { signal });
         let output = "";
         const capture = {
           write(value) {
@@ -1192,6 +1321,10 @@ async function main() {
   } finally {
     unwatchPlayback();
     unwatchGeneration();
+    unwatchGenerationSetup();
+    // A download or uv run this process owns would keep it alive after the room closes; it stops and
+    // resumes next time. One owned by the other window or terminal runs on.
+    await generationSetup?.close?.();
     // A made track still playing is stopped while the generator listens, so its outcome is kept.
     if (localGenerator) {
       previewPlayer?.stop?.();
@@ -1200,6 +1333,7 @@ async function main() {
     unobservePlayer?.();
     unobserveStream?.();
     unwatchStreamGeneration?.();
+    unwatchStreamMusicApp?.();
     atmosphereStream?.stop("closed");
     listeningUpkeep?.stop();
     lyrics?.close();

package/src/core/apple-projection-domain-services.mjs

@@ -1296,6 +1296,10 @@ export class AppleProjectionDomainServices {
     return this.#listeningHistoryStore?.recentAttention?.({ subjectId: this.#subjectId }) ?? null;
   }
 
+  listeningDays() {
+    return this.#listeningHistoryStore?.listeningDays?.({ subjectId: this.#subjectId }) ?? null;
+  }
+
   // Moondog's suggestions ledger and the declared mix (src/profile/moondog-suggestions.mjs).
   recordMoondogSuggestions(entries) {
     return this.#listeningHistoryStore?.recordMoondogSuggestions?.({ entries }) ?? null;

package/src/core/capability-catalog.mjs

@@ -7,6 +7,11 @@ const catalog = [
     description: "Inspect or change the current music service through the same saved selection as the host's service picker.",
     agent_tool: { name: "moondog_playback_service", label: N_("Choose a music service") },
   },
+  {
+    id: "settings", version: "1", state: "enabled", effect: "write_local",
+    description: "Read Moondog's own setup (model, music service, reply language) and change the settings the listener may change by asking.",
+    agent_tool: { name: "moondog_settings", label: N_("Read or change Moondog's settings") },
+  },
   {
     id: "spotify.discovery.search", version: "1", state: "enabled", effect: "read_external", requires_spotify: true,
     description: "Verify open-world music hypotheses with bounded Spotify queries, retaining a shared candidate pool.",
@@ -601,6 +606,50 @@ const catalog = [
       label: N_("Save the playlist to Spotify"),
     },
   },
+  {
+    id: "collection.list",
+    version: "1",
+    state: "enabled",
+    effect: "read_local",
+    description: "Find playlists in the listener's own library on this Mac, by name, with what each holds.",
+    agent_tool: {
+      name: "moondog_collection_list",
+      label: N_("Look in the library"),
+    },
+  },
+  {
+    id: "collection.save",
+    version: "1",
+    state: "enabled",
+    effect: "write_local",
+    description: "Keep songs or tracks Moondog made in the listener's library on this Mac: in Saved, in one of their playlists, or in a new playlist.",
+    agent_tool: {
+      name: "moondog_collection_save",
+      label: N_("Save to the library"),
+    },
+  },
+  {
+    id: "collection.import",
+    version: "1",
+    state: "enabled",
+    effect: "write_local",
+    description: "Import a playlist link from Spotify, Apple Music, NetEase Music or QQ Music into the listener's library on this Mac.",
+    agent_tool: {
+      name: "moondog_collection_import",
+      label: N_("Import a playlist"),
+    },
+  },
+  {
+    id: "collection.play",
+    version: "1",
+    state: "enabled",
+    effect: "play_library",
+    description: "Play a playlist from the listener's library on the music service they chose.",
+    agent_tool: {
+      name: "moondog_collection_play",
+      label: N_("Play from the library"),
+    },
+  },
   {
     id: "music.generate.local",
     version: "1",