@audiofool/moondog 0.3.0-beta.10 → 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.10</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. |
@@ -213,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.10",
+  "version": "0.3.0-beta.11",
   "type": "module",
   "description": "Local-first personal AI music agent.",
   "license": "Apache-2.0",

package/scripts/moondog.mjs

@@ -33,6 +33,7 @@ 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";
@@ -1235,10 +1236,14 @@ async function main() {
       // The desktop window lists models and signs in here, with no terminal.
       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
@@ -1264,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",

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/listening-profile-domain-services.mjs

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

package/src/core/moondog-application.mjs

@@ -740,7 +740,7 @@ export class MoondogApplication {
       found = { provider: "spotify", id: parsed.id, url: parsed.url, name: playlist.name || "Spotify playlist", total: playlist.tracks_total, owned: playlist.owned,
         tracks: playlist.tracks.map((track) => { const credit = track.artists.join(", "); return { id: track.uri, title: track.name, artist: credit,
           ...(track.album ? { album: track.album } : {}), ...(track.isrc ? { isrc: track.isrc } : {}),
-          refs: { spotify_uri: track.uri, spotify_title: track.name, spotify_credit: credit } }; }) };
+          refs: { spotify_uri: track.uri, spotify_title: track.name, spotify_credit: credit, ...(track.image ? { artwork_url: track.image } : {}) } }; }) };
     } else if (parsed.provider === "apple_music") {
       const playlist = await readApplePlaylist(parsed, { signal });
       // A playlist a listener shared has a pl.u- id; the others are Apple's own.
@@ -748,7 +748,8 @@ export class MoondogApplication {
         tracks: playlist.tracks.map((track) => ({ id: track.id, title: track.title, artist: track.artist, refs: { apple_music_id: track.id, ...(track.artwork ? { artwork_url: track.artwork } : {}) } })) };
     } else {
       const playlist = await readPublicPlaylistLink(parsed);
-      found = { ...playlist, owned: null, tracks: playlist.tracks.map((track) => ({ ...track, ...(playlist.provider === "netease" ? { refs: { netease_id: String(track.id) } } : {}) })) };
+      found = { ...playlist, owned: null, tracks: playlist.tracks.map(({ artwork, ...track }) => ({ ...track,
+        refs: { ...(playlist.provider === "netease" ? { netease_id: String(track.id) } : {}), ...(artwork ? { artwork_url: artwork } : {}) } })) };
     }
     signal?.throwIfAborted();
     // A library playlist holds up to 2,000 songs; a longer one comes in from its start, and total says how long it is.
@@ -1404,6 +1405,13 @@ export class MoondogApplication {
     return this.domainServices?.listeningCoverage?.() ?? null;
   }
 
+  // The listener's own plays a day at a time, with the most played artists' and Moondog's own kept
+  // apart, for the window's taste record. Host-only; never a model tool.
+  listeningDays() {
+    if (!this.profileServicesReady()) return null;
+    return this.domainServices?.listeningDays?.() ?? null;
+  }
+
   // What the listener has played lately, apart from the saved reading: stored plays from
   // the last four weeks, and Spotify's own four-week top artists when the room has read them.
   recentAttention() {

package/src/i18n/screen/es.mjs

@@ -713,6 +713,8 @@ export default {
   "Use /taste, or /taste report.": "Usa /taste o /taste report.",
   "Full report above. /taste opens the profile.": "El informe completo está arriba. /taste abre el perfil.",
   "Web lookups aren't available when Moondog is started this way.": "Las consultas web no están disponibles cuando Moondog se abre de esta forma.",
+  "Model roles aren't available when Moondog is started this way.": "Los usos de los modelos no están disponibles cuando Moondog se abre de esta forma.",
+  "Looking at the attached images... Ctrl+C cancels.": "Mirando las imágenes adjuntas... Ctrl+C cancela.",
   "/home doesn't take anything after it.": "/home no admite nada después.",
   "Say anything, or press Tab to look around.": "Di lo que quieras, o pulsa Tab para echar un vistazo.",
   "Use /theme, or /theme paper, charcoal, terminal, or auto.": "Usa /theme, o /theme paper, charcoal, terminal o auto.",

package/src/i18n/screen/ja.mjs

@@ -713,6 +713,8 @@ export default {
   "Use /taste, or /taste report.": "/taste、または /taste report を使ってください。",
   "Full report above. /taste opens the profile.": "完全なレポートは上にあります。/taste でプロフィールを開けます。",
   "Web lookups aren't available when Moondog is started this way.": "この起動方法では Web 検索を使えません。",
+  "Model roles aren't available when Moondog is started this way.": "この起動方法ではモデルの用途を設定できません。",
+  "Looking at the attached images... Ctrl+C cancels.": "添付の画像を見ています... Ctrl+C で取り消します。",
   "/home doesn't take anything after it.": "/home のあとには何も付けません。",
   "Say anything, or press Tab to look around.": "なんでも話しかけてください。Tab で見て回ることもできます。",
   "Use /theme, or /theme paper, charcoal, terminal, or auto.": "/theme、または /theme paper、charcoal、terminal、auto を使ってください。",

package/src/i18n/screen/pt.mjs

@@ -713,6 +713,8 @@ export default {
   "Use /taste, or /taste report.": "Use /taste ou /taste report.",
   "Full report above. /taste opens the profile.": "O relatório completo está acima. /taste abre o perfil.",
   "Web lookups aren't available when Moondog is started this way.": "As consultas na web não estão disponíveis quando o Moondog é aberto deste jeito.",
+  "Model roles aren't available when Moondog is started this way.": "Os usos dos modelos não estão disponíveis quando o Moondog é aberto deste jeito.",
+  "Looking at the attached images... Ctrl+C cancels.": "Olhando as imagens anexadas... Ctrl+C cancela.",
   "/home doesn't take anything after it.": "/home não aceita nada depois.",
   "Say anything, or press Tab to look around.": "Diga qualquer coisa, ou aperte Tab para dar uma olhada.",
   "Use /theme, or /theme paper, charcoal, terminal, or auto.": "Use /theme, ou /theme paper, charcoal, terminal ou auto.",

package/src/i18n/screen/zh.mjs

@@ -713,6 +713,8 @@ export default {
   "Use /taste, or /taste report.": "使用 /taste 或 /taste report。",
   "Full report above. /taste opens the profile.": "完整报告在上面。/taste 打开资料。",
   "Web lookups aren't available when Moondog is started this way.": "这种启动方式不支持网页查询。",
+  "Model roles aren't available when Moondog is started this way.": "这种启动方式不支持设置模型用途。",
+  "Looking at the attached images... Ctrl+C cancels.": "正在看附上的图片…… Ctrl+C 取消。",
   "/home doesn't take anything after it.": "/home 后面不需要加内容。",
   "Say anything, or press Tab to look around.": "随便说点什么，或按 Tab 四处看看。",
   "Use /theme, or /theme paper, charcoal, terminal, or auto.": "使用 /theme，或 /theme paper、charcoal、terminal 或 auto。",

package/src/integrations/playlist-links.mjs

@@ -90,7 +90,13 @@ export async function readApplePlaylist({ id, url }, { fetchImpl = fetch, signal
 
 /** A NetEase Music or QQ Music playlist through its public share link, as library songs. */
 export async function readPublicPlaylistLink({ url }, { fetchImpl = fetch } = {}) {
-  const playlist = await fetchPublicPlaylist({ input: url, fetchImpl });
+  // The public reader explains itself in words; the library's surfaces also need its kind, to say it in their language.
+  const playlist = await fetchPublicPlaylist({ input: url, fetchImpl }).catch((error) => {
+    // Only the link checks' own refusals are about the link; any answer the service gave is about the playlist.
+    const aboutLink = /^(Paste a QQ Music|Use a playlist link|Open this share link|This link belongs to another service)/u;
+    if (!error.code) error.code = /^Could not reach/u.test(error.message) ? "playlist_unreachable" : aboutLink.test(error.message) ? "playlist_link_unsupported" : "playlist_unavailable";
+    throw error;
+  });
   return { provider: playlist.provider, id: playlist.id, url: playlist.url, name: playlist.name, total: playlist.total,
-    tracks: playlist.rows.map((row) => ({ id: row.id, title: row.title, artist: row.artist, ...(row.album ? { album: row.album } : {}) })).filter((track) => track.artist) };
+    tracks: playlist.rows.map((row) => ({ id: row.id, title: row.title, artist: row.artist, ...(row.album ? { album: row.album } : {}), ...(row.artwork ? { artwork: row.artwork } : {}) })).filter((track) => track.artist) };
 }

package/src/integrations/public-playlists.mjs

@@ -54,6 +54,30 @@ async function boundedJson(response) {
   catch { throw new Error("The service changed its playlist response or requires sign-in. No music was imported."); }
 }
 
+// A NetEase playlist, as { code, result: { id, name, privacy, trackCount, tracks } }. NetEase's web player reads
+// playlists with v6, which answers every public one, a listener's Liked songs among them, with all its song ids but
+// details for only the first few without a sign-in; the rest come from song/detail, 200 at a time, in the
+// playlist's order. The older endpoint, which some playlists answer with code 20001, is the fallback.
+const NETEASE_SONGS_MAX = 3000;
+async function neteasePlaylist(id, fetchImpl) {
+  const referer = "https://music.163.com/";
+  const current = await boundedJson(await responseFor(`https://music.163.com/api/v6/playlist/detail?id=${id}&n=100000`, fetchImpl, referer)).catch(() => null);
+  const playlist = current?.code === 200 ? current.playlist : null;
+  if (!playlist || !Array.isArray(playlist.trackIds)) {
+    return boundedJson(await responseFor(`https://music.163.com/api/playlist/detail?id=${id}`, fetchImpl, referer));
+  }
+  const ids = playlist.trackIds.map((entry) => String(entry?.id ?? "")).filter((value) => numericId.test(value)).slice(0, NETEASE_SONGS_MAX);
+  const songs = new Map((Array.isArray(playlist.tracks) ? playlist.tracks : []).map((song) => [String(song?.id ?? ""), song]));
+  const missing = ids.filter((songId) => !songs.has(songId));
+  for (let start = 0; start < missing.length; start += 200) {
+    const batch = missing.slice(start, start + 200);
+    const detail = await boundedJson(await responseFor(`https://music.163.com/api/song/detail/?ids=${encodeURIComponent(`[${batch.join(",")}]`)}`, fetchImpl, referer));
+    for (const song of Array.isArray(detail?.songs) ? detail.songs : []) songs.set(String(song?.id ?? ""), song);
+  }
+  return { code: 200, result: { id: playlist.id, name: playlist.name, privacy: playlist.privacy, trackCount: playlist.trackCount ?? ids.length,
+    tracks: ids.map((songId) => songs.get(songId)).filter(Boolean) } };
+}
+
 /** A public QQ Music or NetEase playlist by its share link: { provider, id, url, name, total, rows, skipped }. */
 export async function fetchPublicPlaylist({ input, provider, fetchImpl = fetch }) {
   let url = playlistLink(input);
@@ -70,10 +94,9 @@ export async function fetchPublicPlaylist({ input, provider, fetchImpl = fetch }
   if (!identity) throw new Error("Open this share link in your browser, then copy the full playlist page URL. Song, album and private playlist links are not supported.");
   if (provider && ["qq_music", "netease"].includes(provider) && provider !== identity.provider) throw new Error("This link belongs to another service. Go back and choose that service, or paste the matching playlist link.");
   const qq = identity.provider === "qq_music";
-  const endpoint = qq
-    ? `https://c.y.qq.com/qzone/fcg-bin/fcg_ucc_getcdinfo_byids_cp.fcg?type=1&json=1&utf8=1&onlysong=0&disstid=${identity.id}&format=json`
-    : `https://music.163.com/api/playlist/detail?id=${identity.id}`;
-  const data = await boundedJson(await responseFor(endpoint, fetchImpl, qq ? "https://y.qq.com/" : "https://music.163.com/"));
+  const data = qq
+    ? await boundedJson(await responseFor(`https://c.y.qq.com/qzone/fcg-bin/fcg_ucc_getcdinfo_byids_cp.fcg?type=1&json=1&utf8=1&onlysong=0&disstid=${identity.id}&format=json`, fetchImpl, "https://y.qq.com/"))
+    : await neteasePlaylist(identity.id, fetchImpl);
   const playlist = qq ? data?.cdlist?.[0] : data?.result;
   if ((qq ? data?.code !== 0 || data?.subcode !== 0 : data?.code !== 200) || !playlist
     || (qq ? Number(playlist.dir_show) === 0 : Number(playlist.privacy) === 10)) throw new Error("This playlist is unavailable publicly. Choose a playlist you can open without signing in; no account password or cookies are needed.");
@@ -91,6 +114,8 @@ export async function fetchPublicPlaylist({ input, provider, fetchImpl = fetch }
       title: musicText(qq ? song.songname : song.name),
       artist: musicText(Array.isArray(artists) ? artists.map((artist) => musicText(artist?.name)).filter(Boolean).join(", ") : ""),
       album: musicText(qq ? song.albumname : (song.album ?? song.al)?.name),
+      // NetEase names each album cover on its own image host; it is shown over https.
+      ...(!qq && /^https?:\/\/p[0-9]+\.music\.126\.net\//u.test((song.album ?? song.al)?.picUrl ?? "") ? { artwork: (song.album ?? song.al).picUrl.replace(/^http:/u, "https:") } : {}),
       playlistId: identity.id, playlistName: name, position: index + 1, member: "public-playlist.json",
     };
   }).filter((row) => row.id && row.title);

package/src/integrations/web/deepseek-web.mjs

@@ -69,7 +69,7 @@ export function createDeepSeekWebResearch({ apiKey, fetch: fetchImpl = globalThi
     if (status !== 200) throw serviceError(status, body);
     const title = typeof body.title === "string" && body.title.trim() ? clip(body.title.trim(), 300) : url;
     return webResult({ provider: "deepseek", kind: "read", status: "found", retrievedAt,
-      summary: clip(text, webLimits.textChars), truncated: text.length > webLimits.textChars,
+      summary: clip(text, webLimits.fullTextChars), truncated: text.length > webLimits.fullTextChars,
       sources: [{ title, url, snippet: "", published_at: null }] });
   }
 

package/src/integrations/web/web-research.mjs

@@ -1,3 +1,4 @@
+import { readModelRoles } from "../../runtime/pi/model-roles.mjs";
 import { createPersistentCredentialStore } from "../../runtime/pi/persistent-credential-store.mjs";
 import { createBraveWebResearch } from "./brave-web.mjs";
 import { createCodexWebResearch } from "./codex-web.mjs";
@@ -5,8 +6,13 @@ import { createDeepSeekWebResearch } from "./deepseek-web.mjs";
 import { failure, webProviderName } from "./web-result.mjs";
 
 // Search goes to the first backend that is set up; reading needs a backend that can open pages.
-// MOONDOG_WEB_SEARCH_PROVIDER and MOONDOG_WEB_READ_PROVIDER pick one instead.
+// The web search role in Settings (model-roles.json) picks one instead, and MOONDOG_WEB_SEARCH_PROVIDER
+// and MOONDOG_WEB_READ_PROVIDER pick over that. As in Hermes Agent, a call that fails on the chosen
+// backend is tried once more on each other backend that is set up, so one service being down or out
+// of credit doesn't leave the agent without the web.
 const order = Object.freeze({ search: ["deepseek", "brave", "codex"], read: ["deepseek", "codex"] });
+// Failures that another backend would only repeat.
+const final = new Set(["web_cancelled", "web_input_invalid", "web_url_invalid"]);
 const providerIds = Object.freeze({ deepseek: "deepseek", brave: "brave", codex: "codex_cli" });
 const keys = Object.freeze({
   deepseek: { credential: "deepseek", variable: "DEEPSEEK_API_KEY" },
@@ -33,43 +39,103 @@ export async function createWebResearch({
   credentials = createPersistentCredentialStore(environment),
   fetch = globalThis.fetch,
   createCodex = createCodexWebResearch,
+  readRoles = readModelRoles,
   now,
 } = {}) {
-  let current = { backends: {}, choices: {} };
+  let current = { backends: {}, choices: {}, found: {} };
+
+  // A backend whose key did not change keeps its cache. A working Codex stays; one that was not ready
+  // is checked again, since the listener may have signed in since.
+  async function backendFor(name, found, previous) {
+    if (name === "codex") {
+      const kept = previous?.backends.codex;
+      return kept?.publicStatus().state === "configured" ? kept : createCodex({ environment, now });
+    }
+    const kept = previous?.backends[name] && previous.found[name]?.key === found[name]?.key;
+    return kept ? previous.backends[name] : { deepseek: createDeepSeekWebResearch, brave: createBraveWebResearch }[name]({ apiKey: found[name]?.key, fetch, now });
+  }
 
   async function load(previous) {
     const found = {
       deepseek: await readKey(credentials, environment, keys.deepseek),
       brave: await readKey(credentials, environment, keys.brave),
     };
+    const role = (await readRoles(environment).catch(() => ({}))).web_search?.service ?? null;
     const choices = {};
     for (const kind of ["search", "read"]) {
       const wanted = environment[`MOONDOG_WEB_${kind.toUpperCase()}_PROVIDER`]?.trim().toLowerCase();
-      if (wanted) choices[kind] = order[kind].includes(wanted) ? { name: wanted, override: true } : { name: null, reason: "web_provider_unknown", wanted };
+      if (wanted) choices[kind] = order[kind].includes(wanted) ? { name: wanted, selectedBy: `MOONDOG_WEB_${kind.toUpperCase()}_PROVIDER` } : { name: null, reason: "web_provider_unknown", wanted };
+      // Brave only searches, so with Brave chosen a read still goes to the first backend that can.
+      else if (role && order[kind].includes(role)) choices[kind] = { name: role, selectedBy: "settings" };
       else choices[kind] = { name: order[kind].find((name) => name !== "codex" && found[name]) ?? "codex" };
     }
     const backends = {};
     for (const name of new Set(Object.values(choices).map((choice) => choice.name).filter(Boolean))) {
-      // A backend whose key did not change keeps its cache.
-      const create = { deepseek: createDeepSeekWebResearch, brave: createBraveWebResearch }[name];
-      if (create) {
-        const kept = previous?.backends[name] && previous.found[name]?.key === found[name]?.key;
-        backends[name] = kept ? previous.backends[name] : create({ apiKey: found[name]?.key, fetch, now });
-      }
-      // A working Codex stays; one that was not ready is checked again, since the listener may have signed in since.
-      if (name === "codex") {
-        const kept = previous?.backends.codex;
-        backends.codex = kept?.publicStatus().state === "configured" ? kept : await createCodex({ environment, now });
-      }
+      backends[name] = await backendFor(name, found, previous);
     }
     return { backends, choices, found };
   }
 
+  // The other backends a failed call can go to: ones with a key, and Codex once it is signed in.
+  async function alternatives(kind, tried) {
+    const names = [];
+    for (const name of order[kind]) {
+      if (name === tried) continue;
+      if (name !== "codex" && !current.found[name]) continue;
+      current.backends[name] ??= await backendFor(name, current.found, null);
+      if (name === "codex" && current.backends.codex.publicStatus().state !== "configured") continue;
+      names.push(name);
+    }
+    return names;
+  }
+
+  async function research(kind, input, options) {
+    const first = backend(kind);
+    const name = current.choices[kind].name;
+    let failed;
+    try {
+      const result = await first[kind](input, options);
+      // A page the chosen backend could not read may open on another.
+      if (kind === "search" || result.status !== "unavailable") return result;
+      failed = result;
+    } catch (error) {
+      if (final.has(error?.code) || options?.signal?.aborted) throw error;
+      failed = error;
+    }
+    for (const other of await alternatives(kind, name)) {
+      try {
+        const result = await current.backends[other][kind](input, options);
+        if (kind === "search" || result.status !== "unavailable") return { ...result, fallback_from: providerIds[name] };
+      } catch (error) {
+        if (final.has(error?.code) || options?.signal?.aborted) throw error;
+      }
+    }
+    if (failed instanceof Error) throw failed;
+    return failed;
+  }
+
+  /** Each service, whether it is set up for each operation, and which one the role chose; for Settings. */
+  async function services() {
+    const role = (await readRoles(environment).catch(() => ({}))).web_search?.service ?? null;
+    current.backends.codex ??= await backendFor("codex", current.found, null);
+    const codex = current.backends.codex.publicStatus().state === "configured";
+    return {
+      chosen: role,
+      search: operationStatus("search"),
+      read: operationStatus("read"),
+      services: order.search.map((name) => {
+        const ready = name === "codex" ? codex : Boolean(current.found[name]);
+        return { id: name, provider: providerIds[name], name: webProviderName(providerIds[name]), ready,
+          search: ready, read: ready && order.read.includes(name) };
+      }),
+    };
+  }
+
   function operationStatus(kind) {
     const choice = current.choices[kind];
     if (!choice?.name) return { provider: null, state: "unavailable", reason: choice?.reason ?? "web_provider_unknown", ...(choice?.wanted ? { requested: choice.wanted } : {}) };
     const provider = providerIds[choice.name];
-    const override = choice.override ? { selected_by: `MOONDOG_WEB_${kind.toUpperCase()}_PROVIDER` } : {};
+    const override = choice.selectedBy ? { selected_by: choice.selectedBy } : {};
     if (choice.name === "codex") {
       const codex = current.backends.codex.publicStatus();
       return { provider, state: codex.state, ...(codex.reason ? { reason: codex.reason } : {}), ...override };
@@ -103,8 +169,9 @@ export async function createWebResearch({
   current = await load();
   return {
     publicStatus,
-    search: async (input, options) => backend("search").search(input, options),
-    read: async (input, options) => backend("read").read(input, options),
+    services,
+    search: (input, options) => research("search", input, options),
+    read: (input, options) => research("read", input, options),
     /** Reads keys and settings again, after /auth or /reload. */
     async refresh() {
       const previous = current;

package/src/integrations/web/web-result.mjs

@@ -4,8 +4,12 @@ import Ajv from "ajv";
 
 // Every web backend returns this one result shape, checked by the same rules,
 // so the agent and the screen never need to know which service answered.
+// After Hermes Agent's web tools: a search gives five sources unless the agent asks for up to ten,
+// and a read keeps the page's whole text, handing it out a window at a time; the agent asks for the
+// next window with next_offset instead of losing everything past the first.
 export const webLimits = Object.freeze({
-  sources: 5, snippetChars: 800, textChars: 12_000, cacheMs: 300_000, cacheEntries: 32, responseBytes: 2_000_000,
+  sources: 5, maxSources: 10, snippetChars: 1200, textChars: 15_000, fullTextChars: 200_000,
+  cacheMs: 300_000, cacheEntries: 32, responseBytes: 2_000_000,
 });
 
 // What each backend's text is, so the agent can tell a search engine's snippet from a model's summary.
@@ -19,13 +23,14 @@ export function webProviderName(provider) {
   return backends[provider]?.name ?? null;
 }
 
-const resultSchema = {
+// A backend's result holds a page's whole text; the agent's holds one window of it.
+const resultSchema = (textChars) => ({
   type: "object", additionalProperties: false,
   properties: {
     status: { type: "string", enum: ["found", "not_found", "unavailable"] },
-    summary: { type: "string", maxLength: webLimits.textChars },
+    summary: { type: "string", maxLength: textChars },
     sources: {
-      type: "array", maxItems: webLimits.sources,
+      type: "array", maxItems: webLimits.maxSources,
       items: {
         type: "object", additionalProperties: false,
         properties: {
@@ -39,8 +44,11 @@ const resultSchema = {
     },
   },
   required: ["status", "summary", "sources"],
-};
-const validate = new Ajv({ strict: false }).compile(resultSchema);
+});
+const ajv = new Ajv({ strict: false });
+const validate = ajv.compile(resultSchema(webLimits.fullTextChars));
+const validateWindow = ajv.compile(resultSchema(webLimits.textChars));
+const offsetOf = (value) => (Number.isInteger(value) && value >= 0 ? value : null);
 
 export function failure(code, message) {
   return Object.assign(new Error(message), { code });
@@ -101,7 +109,7 @@ export function webResult({ provider, kind, status, summary = "", sources = [],
 export function projectWebResearchResult(value) {
   const payload = { status: value?.status, summary: value?.summary, sources: value?.sources };
   const backend = backends[value?.provider];
-  if (!validate(payload) || (payload.status === "found" && !payload.sources.length) ||
+  if (!validateWindow(payload) || (payload.status === "found" && !payload.sources.length) ||
       !backend?.content[value.kind] || value.evidence !== backend.evidence || !Number.isFinite(Date.parse(value.retrieved_at))) {
     throw failure("web_output_invalid", `${backend?.name ?? "The web service"} returned an invalid or unsourced research result.`);
   }
@@ -110,6 +118,9 @@ export function projectWebResearchResult(value) {
     retrieved_at: new Date(value.retrieved_at).toISOString(), from_cache: value.from_cache === true,
     content_kind: backend.content[value.kind], trust: "untrusted_web_content", evidence: backend.evidence,
     ...(value.truncated === true ? { truncated: true } : {}),
+    ...(value.kind === "read" && offsetOf(value.total_chars) !== null ? {
+      text_offset: offsetOf(value.text_offset) ?? 0, total_chars: value.total_chars, next_offset: offsetOf(value.next_offset),
+    } : {}),
     summary: cleanText(payload.summary), sources: projectSources(payload.sources),
   };
 }
@@ -131,14 +142,46 @@ export function searchSources(items) {
     if (snippet) seen.add(snippet);
     const date = typeof item.published_at === "string" ? cleanText(item.published_at).slice(0, 100) : "";
     sources.push({ title, url, snippet, published_at: date || null });
-    if (sources.length === webLimits.sources) break;
+    if (sources.length === webLimits.maxSources) break;
   }
   return sources;
 }
 
+// One window of a page's text, ending at a line or word break near the limit when there is one.
+function textWindow(text, offset) {
+  let end = Math.min(text.length, offset + webLimits.textChars);
+  if (end < text.length) {
+    const floor = offset + Math.floor(webLimits.textChars * 0.8);
+    const lineBreak = text.lastIndexOf("\n", end);
+    const space = text.lastIndexOf(" ", end);
+    end = lineBreak > floor ? lineBreak : space > floor ? space : end;
+  }
+  return { summary: text.slice(offset, end), end };
+}
+
+/** What one call asked for: up to `limit` sources of a search, or the window of a read from `offset`. */
+function windowed(result, kind, { limit, offset }) {
+  if (kind === "search") return { ...result, sources: result.sources.slice(0, limit) };
+  const text = result.summary;
+  if (offset > 0 && offset >= text.length) {
+    throw failure("web_input_invalid", `The page has ${text.length} characters, so offset ${offset} is past its end.`);
+  }
+  const { summary, end } = textWindow(text, offset);
+  const more = end < text.length;
+  return { ...result, summary, text_offset: offset, total_chars: text.length, next_offset: more ? end : null,
+    ...(more || result.truncated ? { truncated: true } : {}) };
+}
+
+function integerIn(value, minimum, maximum, fallback, message) {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value) || value < minimum || value > maximum) throw failure("web_input_invalid", message);
+  return value;
+}
+
 /**
  * The parts every backend shares: one query or URL in, a cancellable request,
- * and a five-minute process-local cache of found results.
+ * and a five-minute process-local cache of found results. The cache keeps the whole result, so a
+ * smaller limit or a later window of the same page needs no second request.
  */
 export function createWebOperations({ unavailable = () => null, queryChars = 500, run, now = () => new Date() }) {
   const cache = new Map();
@@ -146,9 +189,14 @@ export function createWebOperations({ unavailable = () => null, queryChars = 500
   async function research(kind, input, { signal } = {}) {
     const blocked = unavailable(kind);
     if (blocked) throw blocked;
-    if (!input || typeof input !== "object" || Object.keys(input).some((key) => key !== (kind === "search" ? "query" : "url"))) {
+    const allowed = kind === "search" ? ["query", "limit"] : ["url", "offset"];
+    if (!input || typeof input !== "object" || Object.keys(input).some((key) => !allowed.includes(key))) {
       throw failure("web_input_invalid", "Supply one search query or public URL.");
     }
+    const view = {
+      limit: integerIn(input.limit, 1, webLimits.maxSources, webLimits.sources, `Ask for 1 to ${webLimits.maxSources} search results.`),
+      offset: integerIn(input.offset, 0, webLimits.fullTextChars, 0, "The offset must be a whole number of characters, from 0."),
+    };
     const value = kind === "read" ? publicWebUrl(input.url) : typeof input.query === "string" ? input.query.trim() : input.query;
     if (typeof value !== "string" || !value) throw failure("web_input_invalid", "The web query or URL is empty.");
     if (value.length > (kind === "search" ? queryChars : 2048)) {
@@ -158,7 +206,7 @@ export function createWebOperations({ unavailable = () => null, queryChars = 500
     const key = `${kind}:${value}`;
     const cached = cache.get(key);
     if (cached && now().getTime() - Date.parse(cached.retrieved_at) < webLimits.cacheMs) {
-      return { ...structuredClone(cached), from_cache: true };
+      return windowed({ ...structuredClone(cached), from_cache: true }, kind, view);
     }
     const controller = new AbortController();
     active.add(controller);
@@ -168,7 +216,7 @@ export function createWebOperations({ unavailable = () => null, queryChars = 500
         cache.set(key, result);
         if (cache.size > webLimits.cacheEntries) cache.delete(cache.keys().next().value);
       }
-      return structuredClone(result);
+      return windowed(structuredClone(result), kind, view);
     } finally {
       active.delete(controller);
     }