@doitian/dsh-music 0.1.1 → 0.1.4

package/lib/dj.js

@@ -8,6 +8,14 @@
  *      candidate pool plus a taste digest go to `ctx.llm.stream()`, and the
  *      model returns the picks and a one-line vibe. This is what makes the DJ
  *      reason about a mood brief rather than only follow similarity edges.
+ *
+ *      The call carries a **session id** ({@link curationSessionId}). A plugin
+ *      cannot set headers on a leaf call — `GenerateOptions` has no `headers`
+ *      field — so the session id is the only identity lever it has, and each
+ *      adapter maps it onto whatever its provider calls a per-conversation
+ *      header (pi-ai emits `x-opencode-session` for the `opencode-go` route).
+ *      Without it the request reaches such a provider looking like an anonymous
+ *      client that ignores its conventions.
  *   2. **Heuristic tier** — always available, no model required: NetEase's own
  *      signals (similar songs, daily recommendations, anonymous new-song feed,
  *      charts, keyword search) scored by artist affinity, novelty, and the
@@ -20,6 +28,8 @@
  * @module dsh-music/dj
  */
 
+import { randomUUID } from 'node:crypto';
+
 /**
  * Render a model-tier failure so its stable code survives.
  *
@@ -47,6 +57,59 @@ const MAX_POOL = 45;
 /** Only the first `MAX_SEEDS` history entries seed similarity expansion. */
 const MAX_SEEDS = 4;
 
+/** Prefix for the minted curation identity, so logs and health read clearly. */
+const SESSION_ID_PREFIX = 'music-dj-';
+
+/**
+ * The provider-visible identity of the DJ's curation conversation.
+ *
+ * Minted once and persisted, so every plan of one installation is the *same*
+ * conversation to the provider: session affinity and prompt caching work, and a
+ * restart does not look like a new client. `config.dj.sessionId` overrides it,
+ * and a store that cannot be written still yields a usable in-memory id.
+ *
+ * @param {import('./session.js').SessionStore} [store] the plugin's store.
+ * @param {string} [configured] an operator-supplied id.
+ * @returns {string} a non-empty session id.
+ */
+export function curationSessionId(store, configured) {
+  if (typeof configured === 'string' && configured.length > 0) return configured;
+  const persisted = store?.settings?.djSessionId;
+  if (typeof persisted === 'string' && persisted.length > 0) return persisted;
+  const minted = `${SESSION_ID_PREFIX}${randomUUID()}`;
+  try {
+    store?.updateSettings?.({ djSessionId: minted });
+  } catch {
+    // A read-only store costs stability across restarts, not correctness now.
+  }
+  return minted;
+}
+
+/**
+ * Build one model-tier request.
+ *
+ * The guard is the point: a leaf call with no `sessionId` still succeeds against
+ * a permissive provider, so the failure this prevents is silent — a request
+ * that quietly stops following the provider's conventions. Throwing here turns
+ * it into a recorded `dj.modelError` instead. No headers are set, because a
+ * leaf call cannot set any.
+ *
+ * @param {object} options
+ * @param {{provider: string, model: string}} options.target the resolved route.
+ * @param {object[]} options.messages the prompt.
+ * @param {string} options.sessionId the provider-visible conversation identity.
+ * @returns {object} the request to hand to `ctx.llm.stream()`.
+ */
+export function curationRequest({ target, messages, sessionId }) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw new Error(
+      'the DJ model call needs a non-empty sessionId: it is the only identity a leaf call can ' +
+        "carry, and the adapter maps it onto the provider's per-conversation header",
+    );
+  }
+  return { ...target, messages, sessionId };
+}
+
 /**
  * @typedef {object} Plan
  * @property {object[]} tracks chosen tracks, in play order.
@@ -63,16 +126,41 @@ export class AiDj {
    * @param {import('./state.js').Player} options.player
    * @param {import('./session.js').SessionStore} options.store
    * @param {() => object | undefined} [options.resolveLlm] returns the LLM service when mounted.
+   * @param {() => {provider: string, model: string, reasoningEffort?: string} | null} [options.readAgentDefault]
+   *   reads the deployment's default model selection — the model a fresh agent
+   *   starts on, which is the same choice the composer picker writes.
+   * @param {string} [options.sessionId] configured curation identity, overriding the minted one.
    * @param {{warn: Function, info: Function, debug: Function}} [options.logger]
    * @param {object} [options.model] `{ provider, model }` enabling the model tier.
    */
-  constructor({ api, player, store, resolveLlm, logger, model = {} } = {}) {
+  constructor({
+    api,
+    player,
+    store,
+    resolveLlm,
+    readAgentDefault,
+    sessionId,
+    logger,
+    model = {},
+  } = {}) {
     this.api = api;
     this.player = player;
     this.store = store;
     this.resolveLlm = resolveLlm;
+    this.readAgentDefault = readAgentDefault;
     this.logger = logger;
     this.model = { provider: model.provider ?? null, model: model.model ?? null };
+    /**
+     * The curation conversation's provider-visible identity. Minted once, then
+     * persisted, so every plan and every restart is the same conversation.
+     */
+    this.sessionId = curationSessionId(store, sessionId);
+    /**
+     * Where the last resolved route came from: `pin`, `agent-default`, or
+     * `discovered`, or `null` when none resolved. Reported by `/music/health`
+     * so "which model actually curated" never has to be inferred.
+     */
+    this.resolvedFrom = null;
     /**
      * Why the model tier last declined, or `null` when it last succeeded.
      *
@@ -105,11 +193,52 @@ export class AiDj {
     return this.model;
   }
 
+  /** The model tier's observable state, for `/music/health`. */
+  modelStatus() {
+    const sessionModel = this.sessionModel();
+    return {
+      /** The route pinned from the panel or the profile patch, if any. */
+      pinned: this.modelConfigured ? `${this.model.provider}/${this.model.model}` : null,
+      /** The deployment's own model, which an unpinned DJ follows. */
+      sessionModel: sessionModel ? `${sessionModel.provider}/${sessionModel.model}` : null,
+      /** Where the last plan's route came from: pin, agent-default, discovered. */
+      resolvedFrom: this.resolvedFrom,
+      /** The identity every model call carries; the provider sees it as a header. */
+      sessionId: this.sessionId,
+    };
+  }
+
   /** Whether a model tier is configured. */
   get modelConfigured() {
     return Boolean(this.model.provider && this.model.model);
   }
 
+  /**
+   * The model the session itself runs on, when the deployment publishes one.
+   *
+   * `agent-default-model` owns this selection, and the composer/command model
+   * picker writes it. Reading it here is what lets the DJ's model be a
+   * *separate* choice: pin `dj.provider`/`dj.model` to curate on something
+   * else, or leave both unset and follow the session.
+   *
+   * @returns {{provider: string, model: string, reasoningEffort?: string} | null}
+   */
+  sessionModel() {
+    try {
+      const selection = this.readAgentDefault?.();
+      if (!selection?.provider || !selection?.model) return null;
+      return {
+        provider: String(selection.provider),
+        model: String(selection.model),
+        ...(selection.reasoningEffort === undefined || selection.reasoningEffort === null
+          ? {}
+          : { reasoningEffort: String(selection.reasoningEffort) }),
+      };
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Enumerate the provider routes and catalogued models the DJ could use, for
    * the player's picker.
@@ -256,18 +385,29 @@ export class AiDj {
   /**
    * Decide which provider route to call.
    *
-   * An explicit pin always wins. Otherwise the gaps are filled from the
-   * registered adapters' catalogues, preferring a pinned provider (or model)
-   * over the first one. Discovery is a convenience, not a recommendation: the
-   * catalogue's first entry is arbitrary, so pinning both fields is the only
-   * way to know which model curates.
+   * An explicit pin always wins. Otherwise the deployment's own model selection
+   * is inherited — `agent-default-model`, which is the same choice the composer
+   * picker writes and therefore the model the agent loop runs on — so the
+   * session model and the DJ's model are two separable decisions that agree
+   * by default. Only when neither exists does discovery run.
+   *
+   * Discovery is a convenience, not a recommendation: the catalogue's first
+   * entry is arbitrary, so pinning both fields is the only way to know which
+   * model curates.
    *
-   * @param {object} llm the mounted LLM service.
-   * @returns {Promise<{provider: string, model: string} | null>}
+   * @param {object} llm the mounted LLM service, for the catalogue.
+   * @returns {Promise<{provider: string, model: string, source: string, reasoningEffort?: string} | null>}
    */
   async #resolveTarget(llm) {
     const pinned = { provider: this.model.provider, model: this.model.model };
-    if (pinned.provider && pinned.model) return pinned;
+    if (pinned.provider && pinned.model) return { ...pinned, source: 'pin' };
+
+    if (!pinned.provider && !pinned.model) {
+      const inherited = this.sessionModel();
+      if (inherited?.provider && inherited.model) return { ...inherited, source: 'agent-default' };
+    }
+
+    if (!llm?.stream) return null;
 
     let providers = [];
     try {
@@ -289,32 +429,20 @@ export class AiDj {
         model = null;
       }
     }
-    return model ? { provider, model } : null;
+    return model ? { provider, model, source: 'discovered' } : null;
   }
 
   /**
-   * Ask the model to choose from the pool.
-   * @returns {Promise<{picks: number[], vibe: string} | null>} `null` when the
-   *   tier is unavailable or answered with nothing usable.
+   * The candidate catalogue and the listener's taste, as one prompt.
+   *
+   * One place builds the prompt, so a leaf call and any future caller reason
+   * about exactly the same brief.
    */
-  async #askModel({ pool, digest, prompt, count }) {
-    const llm = this.resolveLlm?.();
-    if (!llm?.stream) {
-      return this.#decline('no LLM service is mounted (ctx.get("llm") returned nothing)');
-    }
-    const target = await this.#resolveTarget(llm);
-    if (!target?.provider || !target?.model) {
-      return this.#decline(
-        this.model.provider || this.model.model
-          ? `no usable route for the configured provider/model (${this.model.provider ?? '?'}/${this.model.model ?? '?'})`
-          : 'no provider route is registered, and none could be discovered',
-      );
-    }
-
+  #brief({ pool, digest, prompt, count }) {
     const catalogue = pool
       .map((track, index) => `${index}. ${track.name} — ${(track.artists ?? []).join('/')}${track.album ? ` (${track.album})` : ''}`)
       .join('\n');
-    const brief = [
+    return [
       `Mood or request: ${prompt?.trim() || '(none — continue the current listening session)'}`,
       `Currently playing: ${this.player.current() ? `${this.player.current().name} — ${this.player.current().artists.join('/')}` : '(nothing)'}`,
       digest.recentlyPlayed.length ? `Recently played: ${digest.recentlyPlayed.join('; ')}` : '',
@@ -328,8 +456,11 @@ export class AiDj {
     ]
       .filter(Boolean)
       .join('\n');
+  }
 
-    const messages = [
+  /** The two-block user message both transports send: instruction, then brief. */
+  #messages(brief) {
+    return [
       {
         role: 'user',
         content: [
@@ -347,27 +478,82 @@ export class AiDj {
         ],
       },
     ];
+  }
+
+  /**
+   * Turn an answer into ordered candidate indices.
+   *
+   * Tolerant on purpose: a model may wrap the object in prose or a code fence,
+   * and indices outside the pool are dropped rather than trusted.
+   *
+   * @throws {Error} when the answer carries no JSON object or no usable index.
+   */
+  #parseAnswer(text, pool) {
+    const json = /\{[\s\S]*\}/.exec(text ?? '');
+    if (!json) throw new Error('response contained no JSON object');
+    const parsed = JSON.parse(json[0]);
+    const picks = (parsed.picks ?? [])
+      .map((pick) => Number(typeof pick === 'object' ? pick.index : pick))
+      .filter((index) => Number.isInteger(index) && index >= 0 && index < pool.length);
+    if (picks.length === 0) throw new Error('the model returned no usable picks');
+    const seen = new Set();
+    const ordered = [];
+    for (const index of picks) {
+      if (seen.has(index)) continue;
+      seen.add(index);
+      ordered.push(index);
+    }
+    return { picks: ordered, vibe: typeof parsed.vibe === 'string' ? parsed.vibe : '' };
+  }
+
+  /** Record a model-tier success: clear the stale reason and log what ran. */
+  #accept(answer, target) {
+    this.modelError = null;
+    this.player.dj.modelError = null;
+    this.logger?.info?.(
+      `[music] DJ model tier chose ${answer.picks.length} track(s) via ${target.provider}/${target.model}` +
+        `${target.source === 'discovered' ? ' (discovered)' : ''}`,
+    );
+    return { ...answer, target };
+  }
+
+  /**
+   * Ask the model to choose from the pool.
+   *
+   * One leaf call, carrying the DJ's session identity. A failure declines to the
+   * heuristic tier and records the coded reason rather than being retried: a
+   * second full prompt against a provider that just failed is how one outage
+   * becomes two.
+   *
+   * @returns {Promise<{picks: number[], vibe: string} | null>}
+   *   `null` when the tier is unavailable or answered with nothing usable.
+   */
+  async #askModel({ pool, digest, prompt, count }) {
+    const llm = this.resolveLlm?.();
+    if (!llm?.stream) {
+      return this.#decline('no LLM service is mounted (ctx.get("llm") returned nothing)');
+    }
+
+    const target = await this.#resolveTarget(llm);
+    if (!target?.provider || !target?.model) {
+      this.resolvedFrom = null;
+      return this.#decline(
+        this.model.provider || this.model.model
+          ? `no usable route for the configured provider/model (${this.model.provider ?? '?'}/${this.model.model ?? '?'})`
+          : 'no provider route is registered, and none could be discovered',
+      );
+    }
+    this.resolvedFrom = target.source;
 
+    const brief = this.#brief({ pool, digest, prompt, count });
     try {
-      const text = await this.#collect(llm.stream({ ...target, messages }));
-      const json = /\{[\s\S]*\}/.exec(text);
-      if (!json) throw new Error('response contained no JSON object');
-      const parsed = JSON.parse(json[0]);
-      const picks = (parsed.picks ?? [])
-        .map((pick) => Number(typeof pick === 'object' ? pick.index : pick))
-        .filter((index) => Number.isInteger(index) && index >= 0 && index < pool.length);
-      if (picks.length === 0) return this.#decline('the model returned no usable picks');
-      const seen = new Set();
-      const ordered = [];
-      for (const index of picks) {
-        if (seen.has(index)) continue;
-        seen.add(index);
-        ordered.push(index);
-      }
-      this.logger?.info?.(`[music] DJ model tier chose ${ordered.length} track(s) via ${target.provider}/${target.model}`);
-      this.modelError = null;
-      this.player.dj.modelError = null;
-      return { picks: ordered, vibe: typeof parsed.vibe === 'string' ? parsed.vibe : '', target };
+      const request = curationRequest({
+        target,
+        messages: this.#messages(brief),
+        sessionId: this.sessionId,
+      });
+      const text = await this.#collect(llm.stream(request));
+      return this.#accept(this.#parseAnswer(text, pool), target);
     } catch (error) {
       return this.#decline(describeFailure(error));
     }

package/lib/index.js

@@ -22,6 +22,7 @@ import { Netease } from './netease.js';
 import { QrLogin, SessionStore, ANONYMOUS_COOKIE } from './session.js';
 import { Player } from './state.js';
 import { AiDj } from './dj.js';
+import { LikeState } from './likes.js';
 import { MusicRouter } from './router.js';
 
 export const name = 'music';
@@ -129,6 +130,9 @@ export function apply(ctx, config = {}) {
 
   const qr = new QrLogin({ api, store, logger });
 
+  // The account owns its likes; this is the cache the panel's hearts read.
+  const likes = new LikeState({ api, logger });
+
   /**
    * The LLM service is optional: the DJ falls back to its heuristic tier when
    * absent, so the plugin still works in a composition without a model route.
@@ -141,11 +145,39 @@ export function apply(ctx, config = {}) {
     }
   };
 
+  /**
+   * The deployment's default model selection: the route a freshly created agent
+   * starts on, and the same choice the composer/command model picker writes.
+   *
+   * This is the seam that makes the agent-loop model and the DJ's model two
+   * separate decisions. `agent-default-model` owns the first; `dj.provider` /
+   * `dj.model` owns the second; and the DJ follows the session model when the
+   * plugin pins nothing, instead of picking an arbitrary first route.
+   */
+  const readAgentDefault = () => {
+    try {
+      const service = ctx.get?.('agentDefaultModel') ?? ctx.agentDefaultModel;
+      const selection = service?.currentSelection?.();
+      if (!selection?.provider || !selection?.model) return null;
+      return {
+        provider: String(selection.provider),
+        model: String(selection.model),
+        ...(selection.reasoningEffort === undefined ? {} : { reasoningEffort: String(selection.reasoningEffort) }),
+      };
+    } catch {
+      return null;
+    }
+  };
+
   const dj = new AiDj({
     api,
     player,
     store,
     resolveLlm,
+    readAgentDefault,
+    // An operator-supplied identity for the DJ's model calls; otherwise one is
+    // minted on first use and persisted in session.json.
+    sessionId: config.dj?.sessionId,
     logger,
     // The picker's saved choice wins over the profile patch, so a route chosen
     // in the GUI is not silently overridden by a stale `config.dj` pin.
@@ -162,10 +194,24 @@ export function apply(ctx, config = {}) {
   // ------------------------------------------------------------ session boot
   void api
     .fetchAccount()
-    .then((account) => {
+    .then(async (account) => {
       if (account) logger.info(`[music] signed in as ${account.nickname}`);
       else if (api.authenticated) logger.warn('[music] session cookie present but the account check failed');
       else logger.info('[music] anonymous session (search and non-VIP playback only)');
+
+      // The account holds the likes; the local list is a copy the DJ reads.
+      // Reconciling it here keeps that copy honest across a like made on the
+      // phone, and migrates a list an earlier build recorded locally because it
+      // had no endpoint to send it to.
+      try {
+        const likedIds = await api.likedPlaylistIds(account?.uid);
+        if (likedIds) {
+          store.setLikedIds(likedIds);
+          logger.debug(`[music] like mirror reconciled with the account (${likedIds.length} track(s))`);
+        }
+      } catch (error) {
+        logger.warn(`[music] could not read the account's likes: ${error.message}`);
+      }
     })
     .catch((error) => logger.warn(`[music] account check failed: ${error.message}`));
 
@@ -195,6 +241,7 @@ export function apply(ctx, config = {}) {
     store,
     qr,
     dj,
+    likes,
     panelHtml: PANEL_HTML,
     qrcodeJs: QRCODE_JS,
     config,
@@ -206,19 +253,26 @@ export function apply(ctx, config = {}) {
         busy: player.dj.busy,
         source: player.dj.source,
         model: dj.modelConfigured ? `${dj.model.provider}/${dj.model.model}` : null,
-        /** Where the live route came from: the player, the patch, or discovery. */
+        /** Where the live route came from: the player, the patch, or a default. */
         modelSource: store.settings.djProvider || store.settings.djModel
           ? 'panel'
           : config.dj?.provider || config.dj?.model
             ? 'config'
-            : 'discovered',
+            : readAgentDefault()
+              ? 'agent-default'
+              : 'discovered',
         /** Route that actually curated the last batch, model tier or not. */
         lastRoute: player.dj.lastPlan?.route ?? null,
         /** Why the model tier last declined; null once it succeeds. */
         modelError: player.dj.modelError ?? null,
+        /** Where the route comes from, what the last plan resolved, and the
+         *  identity every call carries (the provider sees it as a header). */
+        ...dj.modelStatus(),
         lastPlanAt: player.dj.lastPlanAt,
         error: player.dj.error,
       },
+      /** How much of the account's like state is cached, and why it is not. */
+      likes: likes.status(),
       dataDir,
       session: { authenticated: api.authenticated, nickname: api.account?.nickname ?? null, vip: Boolean(api.account?.vip) },
       uptimeMs: Math.round(process.uptime() * 1000),

package/lib/likes.js

@@ -0,0 +1,169 @@
+/**
+ * NetEase's like state for the tracks the panel is showing.
+ *
+ * A like lives in the account, not in this plugin: `/api/song/like/check` is
+ * where the truth is, and this class is the cache in front of it. Four
+ * properties are deliberate:
+ *
+ *   - **Unknown is not "not liked".** A track nobody has asked about has no
+ *     answer; `isLiked` reads false for it, and `known` says which of the two
+ *     it is. The panel renders a hollow heart either way, so the difference
+ *     only matters to a caller that is about to write.
+ *   - **A refusal is not an answer.** An anonymous session answers `code: 301`
+ *     for every id. Caching that as "not liked" would leave every heart empty
+ *     for the rest of the session, so a refused check caches nothing and is
+ *     retried after a cool-off instead.
+ *   - **A write is authoritative.** `set()` writes through to NetEase and then
+ *     updates the cache, so the panel's next poll does not need a round trip to
+ *     see the change it just made. It never claims a like the account does not
+ *     have: a refused write leaves the cache untouched.
+ *   - **Nothing here is persisted.** The account is the storage; a restart
+ *     re-reads it, and a different account must not inherit the last one's
+ *     answers, which is what `clear()` is for.
+ *
+ * @module dsh-music/likes
+ */
+
+/** How long one answer is trusted before it is asked again. */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+/** Ids per `/api/song/like/check` request; it takes a list, but not a URL. */
+const CHECK_BATCH = 100;
+
+/** How long a refused or failed check waits before trying again. */
+const RETRY_AFTER_MS = 30_000;
+
+export class LikeState {
+  /**
+   * @param {object} options
+   * @param {import('./netease.js').Netease} options.api
+   * @param {{warn: Function, info: Function, debug: Function}} [options.logger]
+   * @param {number} [options.ttlMs] how long one answer stays fresh.
+   * @param {number} [options.batchSize] ids per check request.
+   */
+  constructor({ api, logger, ttlMs = DEFAULT_TTL_MS, batchSize = CHECK_BATCH } = {}) {
+    this.api = api;
+    this.logger = logger;
+    this.ttlMs = ttlMs;
+    this.batchSize = batchSize;
+    /** @type {Map<number, {liked: boolean, at: number}>} */
+    this.answers = new Map();
+    /** @type {Map<number, Promise<void>>} in-flight checks, so polls share one. */
+    this.pending = new Map();
+    /** Earliest time a refused check may be attempted again. */
+    this.retryAt = 0;
+    /** Why the last check did not produce answers, for `/music/health`. */
+    this.error = null;
+  }
+
+  /** The cached answer; false when there is none. See {@link known}. */
+  isLiked(id) {
+    return this.answers.get(Number(id))?.liked === true;
+  }
+
+  /** Whether a fresh answer for this track is cached — either way. */
+  known(id) {
+    const entry = this.answers.get(Number(id));
+    return Boolean(entry) && Date.now() - entry.at < this.ttlMs;
+  }
+
+  /** Forget every answer. A session change invalidates all of them. */
+  clear() {
+    this.answers.clear();
+    this.pending.clear();
+    this.retryAt = 0;
+    this.error = null;
+    return this;
+  }
+
+  /**
+   * Resolve the like state of `ids`, asking NetEase only about the tracks with
+   * no fresh answer. Never throws: a like check must not fail a poll, and an
+   * unresolved id simply stays unknown.
+   */
+  async ensure(ids) {
+    // Nothing can be liked on an anonymous session, so there is nothing to ask.
+    if (!this.api?.authenticated) return;
+    const list = [...new Set([...ids].map(Number).filter(Number.isFinite))];
+    const stale = list.filter((id) => !this.known(id) && !this.pending.has(id));
+    if (stale.length === 0) return;
+    if (Date.now() < this.retryAt) return;
+
+    const work = this.#load(stale).finally(() => {
+      for (const id of stale) this.pending.delete(id);
+    });
+    for (const id of stale) this.pending.set(id, work);
+    await work;
+  }
+
+  /** Ask for `ids` in batches and cache every answer in them. */
+  async #load(ids) {
+    for (let offset = 0; offset < ids.length; offset += this.batchSize) {
+      const chunk = ids.slice(offset, offset + this.batchSize);
+      let result;
+      try {
+        result = await this.api.likedIds(chunk);
+      } catch (error) {
+        this.#coolOff(`like check failed: ${error.message}`);
+        return;
+      }
+      if (!result.ok) {
+        // Not an answer: cache nothing, so signing in or a retry can still
+        // resolve these tracks rather than freezing them as unliked.
+        this.#coolOff(`like check refused (code ${result.code}): ${result.reason}`);
+        return;
+      }
+      const liked = new Set(result.ids);
+      const at = Date.now();
+      for (const id of chunk) this.answers.set(id, { liked: liked.has(id), at });
+      this.error = null;
+    }
+  }
+
+  #coolOff(reason) {
+    this.retryAt = Date.now() + RETRY_AFTER_MS;
+    this.error = reason;
+    this.logger?.debug?.(`[music] ${reason}`);
+  }
+
+  /**
+   * Like or un-like one track on NetEase.
+   *
+   * The account is written first and the cache only follows a confirmed change,
+   * so the panel can never show a heart the account would contradict.
+   *
+   * @param {number|string} trackId
+   * @param {boolean} liked
+   * @returns {Promise<{ok: boolean, id: number, liked?: boolean, code?: number|string, reason?: string}>}
+   */
+  async set(trackId, liked) {
+    const id = Number(trackId);
+    if (!Number.isFinite(id)) {
+      return { ok: false, id: trackId, code: 'BAD_ID', reason: `invalid track id "${trackId}"` };
+    }
+    if (!this.api?.authenticated) {
+      return { ok: false, id, code: 'ANONYMOUS', reason: 'the NetEase session is anonymous' };
+    }
+    let result;
+    try {
+      result = await this.api.likeSong(id, liked);
+    } catch (error) {
+      return { ok: false, id, code: 'NETWORK', reason: error.message };
+    }
+    if (!result.ok) return result;
+    this.answers.set(id, { liked: Boolean(liked), at: Date.now() });
+    this.error = null;
+    return result;
+  }
+
+  /** What the cache holds, for `/music/health`. */
+  status() {
+    return {
+      cached: this.answers.size,
+      pending: this.pending.size,
+      error: this.error,
+    };
+  }
+}
+
+export { CHECK_BATCH, DEFAULT_TTL_MS, RETRY_AFTER_MS };