@audiofool/moondog 0.1.0 → 0.2.0-beta.2

package/src/core/listening-now.mjs

@@ -0,0 +1,108 @@
+// What the listener plays right now, wherever it plays: the Music app on this Mac, Spotify on its
+// active device, or NetEase through ncm-cli, with the playlist, album or queue it plays from.
+// Two players rarely play at once. When they do, one that plays wins over a paused one, then the
+// listener's chosen service, then this order.
+export const LISTENING_ORDER = Object.freeze(["apple_music", "spotify", "netease"]);
+
+export function activeListening(sources, chosen) {
+  const order = [...new Set([chosen, ...LISTENING_ORDER])];
+  const heard = sources.filter((source) => source.song && (source.state === "playing" || source.state === "paused"));
+  return heard.sort((a, b) => (a.state === "playing" ? 0 : 1) - (b.state === "playing" ? 0 : 1) ||
+    order.indexOf(a.service) - order.indexOf(b.service))[0] ?? null;
+}
+
+const songOf = (item) => ({
+  title: item.name ?? item.title ?? "",
+  artists: Array.isArray(item.artists) ? item.artists : [],
+  album: item.album ?? null,
+  duration_ms: Number.isInteger(item.duration_ms) ? item.duration_ms : null,
+  ...(item.track_ref_id ? { track_ref_id: item.track_ref_id } : {}),
+});
+
+// What the Music app plays, as one source. Its playlist's songs come only from a read that asked for them.
+export function musicAppSource(now) {
+  if (!now.song) return { state: now.state, ...(now.reason ? { reason: now.reason } : {}) };
+  const playlist = now.playlist;
+  return {
+    state: now.state,
+    player: "Music app on this Mac",
+    song: songOf(now.song),
+    position_ms: now.position_ms,
+    shuffle: now.shuffle,
+    repeat: now.repeat,
+    from: playlist ? {
+      kind: playlist.library ? "library" : "playlist",
+      name: playlist.name,
+      tracks_total: playlist.tracks_total ?? null,
+      position: playlist.position ?? null,
+      ...(playlist.tracks ? { first_position: playlist.first_position, tracks: playlist.tracks.map(songOf) } : {}),
+    } : null,
+  };
+}
+
+const musicApp = async (application) => musicAppSource(await application.musicApp.nowPlaying({ tracks: true }));
+
+// Spotify reports only the device that plays; reading it costs three or four requests of the quota.
+async function spotify(application, { signal }) {
+  const player = await application.spotifyNowPlaying({ signal });
+  if (player.state !== "available" || !player.item) return { state: "stopped" };
+  const context = player.context ?? null;
+  const [queue, playlist] = await Promise.all([
+    application.spotifyQueueStatus({ signal }).catch((error) => (signal?.aborted ? Promise.reject(error) : null)),
+    context?.type === "playlist"
+      ? application.requireSpotifyService().playingPlaylist({ uri: context.uri }, { signal })
+        .catch((error) => (signal?.aborted ? Promise.reject(error) : { unavailable: String(error?.message ?? error).slice(0, 200) }))
+      : null,
+  ]);
+  const from = context?.type === "playlist"
+    ? { kind: "playlist", name: playlist.name ?? null, tracks_total: playlist.tracks_total ?? null,
+      ...(playlist.tracks ? { first_position: 1, tracks: playlist.tracks.map(songOf) } : {}),
+      ...(playlist.unavailable ? { unavailable: playlist.unavailable } : {}) }
+    : context?.type === "album" ? { kind: "album", name: player.item.album ?? null }
+      : context?.type === "artist" ? { kind: "artist", name: player.item.artists?.[0] ?? null }
+        : context?.type === "collection" ? { kind: "liked_songs", name: "Liked Songs" }
+          : null;
+  return {
+    state: player.is_playing === true ? "playing" : "paused",
+    player: player.device?.name ? `Spotify on ${player.device.name}` : "Spotify",
+    ...(player.device ? { device: { name: player.device.name ?? null, type: player.device.type ?? null } } : {}),
+    song: songOf(player.item),
+    position_ms: player.progress_ms ?? 0,
+    shuffle: player.shuffle_state === true,
+    repeat: player.repeat_state ?? "off",
+    from,
+    next: (queue?.queue ?? []).map(songOf),
+  };
+}
+
+async function netease(application) {
+  const now = await application.neteaseNowPlaying();
+  if (now.state === "stopped" || !now.song) return { state: "stopped" };
+  return {
+    state: now.state,
+    player: "NetEase Music through ncm-cli on this Mac",
+    song: songOf(now.song),
+    position_ms: now.position_ms ?? 0,
+    from: { kind: "moondog_queue", name: null },
+    next: (now.next ?? []).map(songOf),
+  };
+}
+
+/** Every player Moondog can read, the one the listener hears first: { active, sources }. */
+export async function readListeningNow(application, { signal } = {}) {
+  const readers = [
+    application.musicApp?.available ? ["apple_music", () => musicApp(application)] : null,
+    application.spotifyReady() ? ["spotify", () => spotify(application, { signal })] : null,
+    application.neteaseReady() ? ["netease", () => netease(application)] : null,
+  ].filter(Boolean);
+  const sources = await Promise.all(readers.map(async ([service, read]) => {
+    try {
+      return { service, ...(await read()) };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      return { service, state: "unreadable", reason: String(error?.message ?? error).slice(0, 200) };
+    }
+  }));
+  const active = activeListening(sources, application.playbackService);
+  return { active: active?.service ?? null, sources: active ? [active, ...sources.filter((source) => source !== active)] : sources };
+}

package/src/core/listening-profile-domain-services.mjs

@@ -1,4 +1,6 @@
 import { randomUUID } from "node:crypto";
+import { exploreProfileCatalog, profileExplorationInput } from "../profile/profile-exploration.mjs";
+import { createListenerProfileInput } from "../profile/listener-profile-build.mjs";
 import { lyricSeedsFromProfile } from "./lyric-profile.mjs";
 
 import { isUuid } from "./uuid-v5.mjs";
@@ -6,6 +8,7 @@ import { createListeningHistoryProfileProjection } from "../profile/spotify-arch
 import {
   assertExternalPlanDiversity,
   exactTitleArtistMatch,
+  listenerAssertionAvoids,
   safeExternalSource,
   safeExternalTrack,
 } from "./apple-projection-domain-services.mjs";
@@ -75,6 +78,11 @@ function safeCount(value, label) {
   return value;
 }
 
+// A pick leaves out minutes or skips that its plays never recorded.
+function optionalCount(context, key, label) {
+  return context[key] === undefined ? {} : { [key]: safeCount(context[key], label) };
+}
+
 function safeTimestamp(value, label) {
   const cleaned = cleanText(value, 64, label);
   const parsed = Date.parse(cleaned);
@@ -86,15 +94,19 @@ function safeTimestamp(value, label) {
 
 function safeExternalRefs(value) {
   if (value === undefined) return [];
-  if (!Array.isArray(value) || value.length > 1) {
+  if (!Array.isArray(value)) {
+    throw new TypeError("Listening-history provider identity is invalid");
+  }
+  // Only a Spotify track ID is kept for playback. Last.fm, ListenBrainz and
+  // Spotify account-data identities stay in the store.
+  const references = value.filter((reference) => reference?.system === "spotify");
+  if (references.length > 1) {
     throw new TypeError("Listening-history provider identity is invalid");
   }
-  return value.map((reference) => {
+  return references.map((reference) => {
     if (
-      !reference ||
       typeof reference !== "object" ||
       Array.isArray(reference) ||
-      reference.system !== "spotify" ||
       reference.entity_type !== "spotify.track" ||
       typeof reference.external_id !== "string" ||
       !SPOTIFY_TRACK_ID.test(reference.external_id)
@@ -188,18 +200,16 @@ function safeHistoryTrack(value) {
       throw new TypeError("Rediscovery signal is invalid");
     }
     track.rediscovery = {
-      listening_minutes: safeCount(
-        context.listening_minutes,
+      ...optionalCount(
+        context,
+        "listening_minutes",
         "Rediscovery listening minutes",
       ),
       engaged_play_count: safeCount(
         context.engaged_play_count,
         "Rediscovery engaged plays",
       ),
-      explicit_skips: safeCount(
-        context.explicit_skips,
-        "Rediscovery skips",
-      ),
+      ...optionalCount(context, "explicit_skips", "Rediscovery skips"),
       first_played_at: safeTimestamp(
         context.first_played_at,
         "Rediscovery first play",
@@ -217,8 +227,9 @@ function safeHistoryTrack(value) {
               context.peak_year_play_count,
               "Rediscovery peak-year plays",
             ),
-            peak_year_listening_minutes: safeCount(
-              context.peak_year_listening_minutes,
+            ...optionalCount(
+              context,
+              "peak_year_listening_minutes",
               "Rediscovery peak-year minutes",
             ),
           }
@@ -260,8 +271,9 @@ function safeHistoryTrack(value) {
       context.engaged_play_count,
       "Historical-return engaged plays",
     );
-    const explicitSkips = safeCount(
-      context.explicit_skips,
+    const explicitSkips = optionalCount(
+      context,
+      "explicit_skips",
       "Historical-return skips",
     );
     if (
@@ -270,7 +282,7 @@ function safeHistoryTrack(value) {
       latestReturnGapDays < 1 ||
       latestReturnGapDays > longestGapDays ||
       engagedPlayCount > playCount ||
-      explicitSkips > playCount ||
+      (explicitSkips.explicit_skips ?? 0) > playCount ||
       Date.parse(firstPlayedAt) > Date.parse(latestReturnAt) ||
       Date.parse(latestReturnAt) > Date.parse(lastPlayedAt) ||
       !historySupportSignals.has(historicalReturnSignal) ||
@@ -279,12 +291,13 @@ function safeHistoryTrack(value) {
       throw new TypeError("Historical-return candidate is invalid");
     }
     track.historical_return = {
-      listening_minutes: safeCount(
-        context.listening_minutes,
+      ...optionalCount(
+        context,
+        "listening_minutes",
         "Historical-return listening minutes",
       ),
       engaged_play_count: engagedPlayCount,
-      explicit_skips: explicitSkips,
+      ...explicitSkips,
       first_played_at: firstPlayedAt,
       last_played_at: lastPlayedAt,
       return_count: returnCount,
@@ -310,16 +323,15 @@ function safeHistoryTrack(value) {
         context.year_engaged_play_count,
         "Time Machine engaged plays",
       ),
-      year_listening_minutes: safeCount(
-        context.year_listening_minutes,
+      ...optionalCount(
+        context,
+        "year_listening_minutes",
         "Time Machine year minutes",
       ),
-      year_explicit_skips: safeCount(
-        context.year_explicit_skips,
-        "Time Machine year skips",
-      ),
-      lifetime_listening_minutes: safeCount(
-        context.lifetime_listening_minutes,
+      ...optionalCount(context, "year_explicit_skips", "Time Machine year skips"),
+      ...optionalCount(
+        context,
+        "lifetime_listening_minutes",
         "Time Machine lifetime minutes",
       ),
       representative_signal: cleanText(
@@ -335,8 +347,9 @@ function safeHistoryTrack(value) {
       context.engaged_play_count,
       "Back-to-back engaged plays",
     );
-    const explicitSkips = safeCount(
-      context.explicit_skips,
+    const explicitSkips = optionalCount(
+      context,
+      "explicit_skips",
       "Back-to-back skips",
     );
     const burstCount = safeCount(
@@ -363,7 +376,7 @@ function safeHistoryTrack(value) {
       playsInBursts < burstCount * 2 ||
       playsInBursts > playCount ||
       engagedPlayCount > playCount ||
-      explicitSkips > playCount ||
+      (explicitSkips.explicit_skips ?? 0) > playCount ||
       !backToBackSignals.has(sequenceSignal) ||
       !isUuid(context.evidence_id)
     ) {
@@ -371,7 +384,7 @@ function safeHistoryTrack(value) {
     }
     track.back_to_back = {
       engaged_play_count: engagedPlayCount,
-      explicit_skips: explicitSkips,
+      ...explicitSkips,
       burst_count: burstCount,
       maximum_consecutive_plays: maximumConsecutivePlays,
       plays_in_bursts: playsInBursts,
@@ -409,6 +422,8 @@ export class ListeningProfileDomainServices {
   #store;
   #subjectId;
   #candidateSets = new Map();
+  #profileBuildInput;
+  #ownsStore = true;
 
   constructor({ listeningHistoryStore, subjectId } = {}) {
     if (
@@ -426,6 +441,18 @@ export class ListeningProfileDomainServices {
     this.#subjectId = subjectId.toLowerCase();
   }
 
+  // Each conversation that runs beside another gets a fork: the same store with its own
+  // candidate sets, so one conversation's prompt never clears another's. Only the
+  // original closes the store.
+  fork() {
+    const fork = new ListeningProfileDomainServices({
+      listeningHistoryStore: this.#store,
+      subjectId: this.#subjectId,
+    });
+    fork.#ownsStore = false;
+    return fork;
+  }
+
   status() {
     return {
       state: "ready",
@@ -458,6 +485,14 @@ export class ListeningProfileDomainServices {
     };
   }
 
+  listeningCoverage() {
+    return this.#store.listeningCoverage?.({ subjectId: this.#subjectId }) ?? null;
+  }
+
+  recentAttention() {
+    return this.#store.recentAttention?.({ subjectId: this.#subjectId }) ?? null;
+  }
+
   rediscoveryReady() {
     return typeof this.#store.rediscoveryCandidates === "function";
   }
@@ -518,7 +553,19 @@ export class ListeningProfileDomainServices {
     return { candidateSetId, tracks: prepared };
   }
 
-  registerExternalCandidateSet({ tracks, source } = {}) {
+  filterDiscoveryTracks(tracks) {
+    const avoids = this.#store.activeAvoidances?.({ subjectId: this.#subjectId }) ??
+      this.#store.profileSummary({ subjectId: this.#subjectId })?.listener_assertions?.avoids ?? [];
+    return tracks.filter((track) => !listenerAssertionAvoids(
+      { listener_assertions: { avoids } }, "track", track.title, track.artist_credit,
+    ));
+  }
+
+  isKnownDiscoveryTrack(track) {
+    return (this.#store.listenedTracks?.({ subjectId: this.#subjectId }) ?? []).some(heard => exactTitleArtistMatch(track, heard));
+  }
+
+  registerExternalCandidateSet({ tracks, source, excludeKnown = true } = {}) {
     if (!Array.isArray(tracks) || tracks.length < 1 || tracks.length > HISTORY_MAX_ITEMS) {
       throw new TypeError("External catalog candidates are invalid");
     }
@@ -530,14 +577,16 @@ export class ListeningProfileDomainServices {
     if (new Set(prepared.map((track) => track.track_ref_id)).size !== prepared.length) {
       throw new TypeError("External catalog candidates are duplicated");
     }
-    // Outside suggestions should be new to the listener, so drop anything already played.
+    // Familiarity is useful evidence, not an automatic discovery exclusion.
     const listened = typeof this.#store.listenedTracks === "function"
       ? this.#store.listenedTracks({ subjectId: this.#subjectId })
       : [];
     const accepted = [];
     let excludedHistoryMatches = 0;
-    for (const track of prepared) {
-      if (listened.some((heard) => exactTitleArtistMatch(track, heard))) {
+    const allowed = this.filterDiscoveryTracks(prepared);
+    for (const track of allowed) {
+      const heard = listened.some((heard) => exactTitleArtistMatch(track, heard));
+      if (excludeKnown && heard) {
         excludedHistoryMatches += 1;
         continue;
       }
@@ -545,7 +594,7 @@ export class ListeningProfileDomainServices {
         ...track,
         knownness: {
           imported_library: "not_imported",
-          listening_history: "not_found_by_exact_title_artist",
+          listening_history: heard ? "found_by_exact_title_artist" : "not_found_by_exact_title_artist",
         },
       });
     }
@@ -560,6 +609,7 @@ export class ListeningProfileDomainServices {
       candidate_set_id: registered,
       candidate_scope: "external_catalog",
       result_count: accepted.length,
+      excluded_avoided_matches: prepared.length - allowed.length,
       excluded_library_matches: excludedHistoryMatches,
       expires_on: "prompt_end",
       source: trustedSource,
@@ -584,6 +634,35 @@ export class ListeningProfileDomainServices {
     return createListeningHistoryProfileProjection(listening, { maxItems });
   }
 
+  profileExplorationReady() {
+    return typeof this.#store.profileCatalog === "function";
+  }
+
+  async exploreProfile(argumentsValue) {
+    const input = profileExplorationInput(argumentsValue);
+    return exploreProfileCatalog({ listening: this.#store.profileCatalog({ subjectId: this.#subjectId }), input });
+  }
+
+  profileBuildReady() {
+    return typeof this.#store.listenerProfileStorage === "function";
+  }
+
+  getListenerProfileStore() {
+    return this.#store.listenerProfileStorage({ subjectId: this.#subjectId });
+  }
+
+  getProfileBuildContext() {
+    const version = this.#store.profileDataVersion();
+    if (this.#profileBuildInput?.version !== version) {
+      this.#profileBuildInput = { version, input: createListenerProfileInput({
+        subjectId: this.#subjectId,
+        evidenceRevision: this.#store.profileEvidenceRevision({ subjectId: this.#subjectId }),
+        listening: this.#store.profileCatalog({ subjectId: this.#subjectId }),
+      }) };
+    }
+    return { store: this.getListenerProfileStore(), input: this.#profileBuildInput.input };
+  }
+
   async getRediscoveryCandidates(argumentsValue) {
     const input = modelArguments(argumentsValue, new Set(["limit"]));
     const limit = boundedHistoryItems(input.limit);
@@ -896,6 +975,11 @@ export class ListeningProfileDomainServices {
     ) {
       throw new TypeError("A playlist plan cannot contain duplicate tracks");
     }
+    const external = selected.map(({ track }) => track)
+      .filter((track) => track.candidate_scope === "external_catalog");
+    if (this.filterDiscoveryTracks(external).length !== external.length) {
+      throw new Error("An external discovery is currently marked Avoid. Choose another track.");
+    }
     const tracks = selected.map(({ track, selectionReason }, index) => ({
       position: index + 1,
       track_ref_id: track.track_ref_id,
@@ -972,13 +1056,41 @@ export class ListeningProfileDomainServices {
     ) {
       throw new TypeError("Retained playlist candidates are invalid");
     }
-    const registered = this.#registerHistoryTracks(tracks);
+    if (this.#candidateSets.size >= CANDIDATE_SETS_MAX) {
+      throw new Error("The prompt has reached its candidate set limit");
+    }
+    const prepared = tracks.map((track) =>
+      track?.candidate_scope === "external_catalog"
+        ? {
+            ...safeExternalTrack(track),
+            knownness: {
+              imported_library: "not_imported",
+              listening_history: "not_found_by_exact_title_artist",
+            },
+          }
+        : safeHistoryTrack(track),
+    );
+    if (
+      new Set(prepared.map((track) => track.track_ref_id)).size !==
+      prepared.length
+    ) {
+      throw new TypeError("Retained playlist candidates are duplicated");
+    }
+    const candidateSetId = randomUUID();
+    this.#candidateSets.set(
+      candidateSetId,
+      new Map(
+        prepared.map((track) => [track.track_ref_id, structuredClone(track)]),
+      ),
+    );
+    const scopes = new Set(prepared.map((track) => track.candidate_scope));
     return {
-      candidate_set_id: registered.candidateSetId,
-      candidate_scope: "private_history",
-      result_count: registered.tracks.length,
+      candidate_set_id: candidateSetId,
+      candidate_scope: scopes.size === 1 ? [...scopes][0] : "mixed",
+      result_count: prepared.length,
       expires_on: "prompt_end",
-      tracks: registered.tracks.map(publicHistoryTrack),
+      source: "retained_validated_playlist",
+      tracks: prepared.map(publicHistoryTrack),
     };
   }
 
@@ -1001,7 +1113,7 @@ export class ListeningProfileDomainServices {
 
   close() {
     this.resetCandidateSets();
-    this.#store.close();
+    if (this.#ownsStore) this.#store.close();
   }
 }
 

package/src/core/listening-upkeep.mjs

@@ -0,0 +1,31 @@
+// Spotify keeps only a listener's last 50 plays, about three hours of listening. The
+// room runs its listening upkeep when it opens and every half hour while it runs: it
+// reads recent plays before they fall out, then rebuilds the saved reading when due.
+export const LISTENING_UPKEEP_INTERVAL_MS = 30 * 60_000;
+
+export function startListeningUpkeep({ run, intervalMs = LISTENING_UPKEEP_INTERVAL_MS }) {
+  let running = null;
+  let stopped = false;
+  const tick = async () => {
+    // A rebuild can outlast the half hour; the next tick waits for the one after.
+    if (stopped || running) return;
+    running = new AbortController();
+    try {
+      await run({ signal: running.signal });
+    } catch {
+      // Signed out, offline or rate limited: the next tick tries again, and nothing waits on this one.
+    } finally {
+      running = null;
+    }
+  };
+  const timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+  tick();
+  return {
+    stop() {
+      stopped = true;
+      clearInterval(timer);
+      running?.abort();
+    },
+  };
+}