@mercury-fw/core 0.25.0

package/src/admin/cli-routes.ts

@@ -0,0 +1,48 @@
+/**
+ * Admin panel's CLI status tab: lists each active CLI's allowlisted
+ * commands straight from the same `CliConfig` `src/index.ts` already
+ * built at startup (`activeCliConfigs`), and — where a CLI declares a
+ * plain, non-mutating `auth whoami`-shaped prefix — runs it through the
+ * exact same `runCli` used for real tool calls. Never constructs or runs
+ * anything else; this is read-only status, not a command console.
+ */
+import type { CliConfig } from "@mercury-fw/cli-engine";
+import type { runCli } from "@mercury-fw/cli-engine";
+
+export type CliStatusEntry = {
+  binary: string;
+  allowedPrefixes: CliConfig["allowedPrefixes"];
+  whoami: { available: false } | { available: true; ok: boolean; output: string };
+};
+
+function findWhoamiPrefix(config: CliConfig): string[] | null {
+  const match = config.allowedPrefixes.find(
+    (c) => !c.confirm && c.prefix.length === 2 && c.prefix[0] === "auth" && c.prefix[1] === "whoami",
+  );
+  return match ? match.prefix : null;
+}
+
+export async function getCliStatus(
+  configs: Record<string, CliConfig>,
+  runCliFn: typeof runCli,
+): Promise<CliStatusEntry[]> {
+  const entries: CliStatusEntry[] = [];
+  for (const [binary, config] of Object.entries(configs)) {
+    const whoamiPrefix = findWhoamiPrefix(config);
+    if (!whoamiPrefix) {
+      entries.push({ binary, allowedPrefixes: config.allowedPrefixes, whoami: { available: false } });
+      continue;
+    }
+    const result = await runCliFn(binary, whoamiPrefix);
+    entries.push({
+      binary,
+      allowedPrefixes: config.allowedPrefixes,
+      whoami: {
+        available: true,
+        ok: result.ok,
+        output: result.ok ? String(result.data) : result.error,
+      },
+    });
+  }
+  return entries;
+}

package/src/admin/env-file.ts

@@ -0,0 +1,29 @@
+/**
+ * Targeted single-key rewrite of a `.env` file's raw text — used by the
+ * admin panel's allowlisted env editor (see `env-routes.ts`). Only the
+ * matched key's own line changes; every other line (including any secret
+ * sitting right next to it) is passed through byte-identical. `content`
+ * in, `content` out — no filesystem access here, so it's trivially testable.
+ */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function setEnvValue(content: string, key: string, value: string): string {
+  const linePattern = new RegExp(`^${escapeRegExp(key)}=`);
+  let found = false;
+  const lines = content.split("\n").map((line) => {
+    if (!found && linePattern.test(line)) {
+      found = true;
+      return `${key}=${value}`;
+    }
+    return line;
+  });
+
+  if (found) {
+    return lines.join("\n");
+  }
+
+  const needsNewlineBefore = content.length > 0 && !content.endsWith("\n");
+  return `${content}${needsNewlineBefore ? "\n" : ""}${key}=${value}\n`;
+}

package/src/admin/model-routes.ts

@@ -0,0 +1,71 @@
+/**
+ * Admin panel's Model tab (Ollama host/model/context-length/reachability)
+ * and the self+dependency health check that stands in for "container
+ * status" (see plan §5 — no Docker socket access, so this is Mercury's
+ * own process plus its two real dependencies, not `docker compose ps`).
+ */
+import { getLoadedContextLength } from "../model/context-size.ts";
+
+type OllamaTagsResponse = { models?: Array<{ name: string }> };
+
+/** Live model names Ollama actually has pulled, or `null` if the host isn't reachable. */
+export async function getAvailableModels(host: string, fetchFn: typeof fetch = fetch): Promise<string[] | null> {
+  try {
+    const response = await fetchFn(`${host}/api/tags`);
+    if (!response.ok) return null;
+    const data = (await response.json()) as OllamaTagsResponse;
+    return data.models?.map((m) => m.name) ?? [];
+  } catch {
+    return null;
+  }
+}
+
+export type ModelStatus = {
+  host: string;
+  model: string;
+  contextLength: number | null;
+  availableModels: string[] | null;
+};
+
+export async function getModelStatus(
+  host: string,
+  model: string,
+  fetchFn: typeof fetch = fetch,
+): Promise<ModelStatus> {
+  // getLoadedContextLength (unlike getAvailableModels) doesn't catch its own
+  // fetch failures — an unreachable host makes it throw, which would
+  // otherwise take the whole status endpoint down with it.
+  const [contextLength, availableModels] = await Promise.all([
+    getLoadedContextLength(host, model, fetchFn).catch(() => null),
+    getAvailableModels(host, fetchFn),
+  ]);
+  return { host, model, contextLength, availableModels };
+}
+
+export type SelfHealth = {
+  uptimeSeconds: number;
+  memory: { rss: number; heapUsed: number; heapTotal: number };
+  qdrantReachable: boolean;
+  ollamaReachable: boolean;
+};
+
+export async function getSelfHealth(deps: {
+  qdrant: { getCollections(): Promise<unknown> };
+  ollamaHost: string;
+  fetchFn?: typeof fetch;
+}): Promise<SelfHealth> {
+  const [qdrantReachable, availableModels] = await Promise.all([
+    deps.qdrant
+      .getCollections()
+      .then(() => true)
+      .catch(() => false),
+    getAvailableModels(deps.ollamaHost, deps.fetchFn),
+  ]);
+  const memory = process.memoryUsage();
+  return {
+    uptimeSeconds: process.uptime(),
+    memory: { rss: memory.rss, heapUsed: memory.heapUsed, heapTotal: memory.heapTotal },
+    qdrantReachable,
+    ollamaReachable: availableModels !== null,
+  };
+}

package/src/admin/public/index.html

@@ -0,0 +1,416 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Mercury admin (POC)</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font-family: system-ui, sans-serif; margin: 0; padding: 0; }
+  header { padding: 0.75rem 1rem; border-bottom: 1px solid #8884; display: flex; align-items: center; gap: 1rem; }
+  header h1 { font-size: 1rem; margin: 0; }
+  nav { display: flex; gap: 0.25rem; padding: 0.5rem 1rem; border-bottom: 1px solid #8884; flex-wrap: wrap; }
+  nav button { padding: 0.4rem 0.8rem; border: 1px solid #8884; background: transparent; cursor: pointer; border-radius: 4px; }
+  nav button[aria-selected="true"] { background: #8882; font-weight: 600; }
+  main { padding: 1rem; max-width: 100%; overflow-x: auto; }
+  section { display: none; }
+  section[aria-hidden="false"] { display: block; }
+  textarea, input[type=text], input[type=number], select { font-family: inherit; font-size: 0.9rem; padding: 0.3rem; }
+  textarea { width: 100%; min-height: 6rem; box-sizing: border-box; }
+  pre { white-space: pre-wrap; word-break: break-word; background: #8881; padding: 0.6rem; border-radius: 4px; max-height: 24rem; overflow: auto; }
+  table { border-collapse: collapse; width: 100%; font-size: 0.85rem; }
+  th, td { text-align: left; padding: 0.3rem 0.5rem; border-bottom: 1px solid #8883; vertical-align: top; }
+  .row { display: flex; gap: 0.5rem; align-items: center; flex-wrap: wrap; margin: 0.4rem 0; }
+  .cols { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
+  .muted { opacity: 0.7; font-size: 0.85rem; }
+  .list { list-style: none; padding: 0; margin: 0; max-height: 20rem; overflow: auto; border: 1px solid #8883; border-radius: 4px; }
+  .list li { padding: 0.25rem 0.5rem; cursor: pointer; }
+  .list li:hover { background: #8882; }
+  fieldset { border: 1px solid #8883; border-radius: 4px; margin: 0.6rem 0; }
+  button.primary { font-weight: 600; }
+  .status-ok { color: #2a2; }
+  .status-bad { color: #c33; }
+</style>
+</head>
+<body>
+<header>
+  <h1>Mercury admin — POC</h1>
+  <span class="muted">throwaway panel, local only, no auth</span>
+</header>
+<nav id="tabs"></nav>
+<main id="panels"></main>
+
+<script>
+const TABS = ["Wiki", "Qdrant", "CLI", "Model", "System prompt", "Tool log", "Env"];
+const tabsEl = document.getElementById("tabs");
+const panelsEl = document.getElementById("panels");
+let active = TABS[0];
+
+function renderNav() {
+  tabsEl.innerHTML = "";
+  for (const t of TABS) {
+    const b = document.createElement("button");
+    b.textContent = t;
+    b.setAttribute("aria-selected", String(t === active));
+    b.onclick = () => { active = t; renderNav(); showPanel(t); };
+    tabsEl.appendChild(b);
+  }
+}
+
+function panel(id) {
+  return document.getElementById("panel-" + id);
+}
+
+function showPanel(t) {
+  for (const el of panelsEl.children) {
+    el.setAttribute("aria-hidden", String(el.id !== "panel-" + t));
+  }
+  const loader = loaders[t];
+  if (loader) loader();
+}
+
+async function api(path, opts) {
+  const res = await fetch(path, opts);
+  const data = await res.json();
+  if (!data.ok) throw new Error(data.error || "request failed");
+  return data;
+}
+
+function el(html) {
+  const t = document.createElement("template");
+  t.innerHTML = html.trim();
+  return t.content.firstChild;
+}
+
+// ---------- Wiki ----------
+function buildWikiPanel() {
+  const p = el(`<section id="panel-Wiki" aria-hidden="true">
+    <div class="cols">
+      <div>
+        <div class="row"><button id="wiki-refresh">Refresh list</button></div>
+        <ul class="list" id="wiki-list"></ul>
+        <div class="row">
+          <input type="text" id="wiki-grep-pattern" placeholder="" />
+          <button id="wiki-grep-btn">Serach</button>
+        </div>
+        <pre id="wiki-grep-results"></pre>
+      </div>
+      <div>
+        <h3 id="wiki-read-path" class="muted">(select a file)</h3>
+        <pre id="wiki-read-content"></pre>
+
+        <fieldset>
+          <legend>Edit a curated note (via the model, real turn)</legend>
+          <textarea id="wiki-edit-instruction" placeholder='e.g. "update curated/standards/x.md to say..."'></textarea>
+          <div class="row"><button id="wiki-edit-btn" class="primary">Send to Mercury</button></div>
+          <pre id="wiki-edit-reply"></pre>
+        </fieldset>
+
+        <fieldset>
+          <legend>Write a raw/ entry (direct, no model)</legend>
+          <input type="text" id="wiki-raw-path" placeholder="raw/some-note.md" style="width:100%;box-sizing:border-box;" />
+          <textarea id="wiki-raw-content" placeholder="verbatim content"></textarea>
+          <div class="row"><button id="wiki-raw-btn">Write raw entry</button></div>
+        </fieldset>
+
+        <fieldset>
+          <legend>Delete curated/ or raw/ entry (direct, no model)</legend>
+          <div class="row">
+            <input type="text" id="wiki-delete-path" placeholder="curated/x.md or raw/x.md" />
+            <button id="wiki-delete-btn">Delete</button>
+          </div>
+        </fieldset>
+      </div>
+    </div>
+  </section>`);
+
+  p.querySelector("#wiki-refresh").onclick = loadWikiList;
+  p.querySelector("#wiki-grep-btn").onclick = async () => {
+    const pattern = p.querySelector("#wiki-grep-pattern").value;
+    const out = p.querySelector("#wiki-grep-results");
+    try {
+      const { matches } = await api("/api/wiki/grep?pattern=" + encodeURIComponent(pattern));
+      out.textContent = matches.map(m => `${m.path}:${m.line}: ${m.text}`).join("\n") || "(no matches)";
+    } catch (e) { out.textContent = "error: " + e.message; }
+  };
+  p.querySelector("#wiki-edit-btn").onclick = async () => {
+    const instruction = p.querySelector("#wiki-edit-instruction").value;
+    const out = p.querySelector("#wiki-edit-reply");
+    out.textContent = "working...";
+    try {
+      const { reply } = await api("/api/wiki/edit", { method: "POST", headers: jsonHeaders, body: JSON.stringify({ instruction }) });
+      out.textContent = reply;
+      loadWikiList();
+    } catch (e) { out.textContent = "error: " + e.message; }
+  };
+  p.querySelector("#wiki-raw-btn").onclick = async () => {
+    const path = p.querySelector("#wiki-raw-path").value;
+    const content = p.querySelector("#wiki-raw-content").value;
+    try {
+      await api("/api/wiki/raw", { method: "POST", headers: jsonHeaders, body: JSON.stringify({ path, content }) });
+      loadWikiList();
+    } catch (e) { alert("error: " + e.message); }
+  };
+  p.querySelector("#wiki-delete-btn").onclick = async () => {
+    const path = p.querySelector("#wiki-delete-path").value;
+    if (!confirm(`Delete "${path}"? This is a real git commit removing the file.`)) return;
+    try {
+      await api("/api/wiki/entry?path=" + encodeURIComponent(path), { method: "DELETE" });
+      loadWikiList();
+    } catch (e) { alert("error: " + e.message); }
+  };
+
+  return p;
+}
+
+async function loadWikiList() {
+  const listEl = panel("Wiki").querySelector("#wiki-list");
+  listEl.innerHTML = "loading...";
+  try {
+    const { files } = await api("/api/wiki/list");
+    listEl.innerHTML = "";
+    for (const f of files) {
+      const li = document.createElement("li");
+      li.textContent = f;
+      li.onclick = async () => {
+        panel("Wiki").querySelector("#wiki-read-path").textContent = f;
+        const out = panel("Wiki").querySelector("#wiki-read-content");
+        out.textContent = "loading...";
+        try {
+          const { content } = await api("/api/wiki/read?path=" + encodeURIComponent(f));
+          out.textContent = content;
+        } catch (e) { out.textContent = "error: " + e.message; }
+      };
+      listEl.appendChild(li);
+    }
+  } catch (e) { listEl.textContent = "error: " + e.message; }
+}
+
+// ---------- Qdrant ----------
+function buildQdrantPanel() {
+  const p = el(`<section id="panel-Qdrant" aria-hidden="true">
+    <div class="row">
+      <button id="qdrant-refresh">List collections</button>
+      <select id="qdrant-collection"></select>
+      <input type="number" id="qdrant-limit" value="20" style="width:5rem;" />
+      <button id="qdrant-scroll-btn">Scroll</button>
+    </div>
+    <pre id="qdrant-collections"></pre>
+    <pre id="qdrant-points"></pre>
+  </section>`);
+
+  p.querySelector("#qdrant-refresh").onclick = async () => {
+    const out = p.querySelector("#qdrant-collections");
+    const select = p.querySelector("#qdrant-collection");
+    try {
+      const { collections } = await api("/api/qdrant/collections");
+      out.textContent = JSON.stringify(collections, null, 2);
+      select.innerHTML = "";
+      for (const c of collections) {
+        const opt = document.createElement("option");
+        opt.value = c.name; opt.textContent = c.name;
+        select.appendChild(opt);
+      }
+    } catch (e) { out.textContent = "error: " + e.message; }
+  };
+  p.querySelector("#qdrant-scroll-btn").onclick = async () => {
+    const collection = p.querySelector("#qdrant-collection").value;
+    const limit = p.querySelector("#qdrant-limit").value;
+    const out = p.querySelector("#qdrant-points");
+    if (!collection) { out.textContent = "list collections first"; return; }
+    try {
+      const page = await api(`/api/qdrant/scroll?collection=${encodeURIComponent(collection)}&limit=${limit}`);
+      out.textContent = JSON.stringify(page.points, null, 2) + `\n\nnextOffset: ${JSON.stringify(page.nextOffset)}`;
+    } catch (e) { out.textContent = "error: " + e.message; }
+  };
+  return p;
+}
+
+// ---------- CLI ----------
+function buildCliPanel() {
+  return el(`<section id="panel-CLI" aria-hidden="true">
+    <div class="row"><button id="cli-refresh">Refresh</button></div>
+    <div id="cli-table"></div>
+  </section>`);
+}
+async function loadCli() {
+  const p = panel("CLI");
+  if (!p.querySelector("#cli-refresh").onclick) {
+    p.querySelector("#cli-refresh").onclick = loadCli;
+  }
+  const out = p.querySelector("#cli-table");
+  out.textContent = "loading...";
+  try {
+    const { clis } = await api("/api/cli/status");
+    out.innerHTML = "";
+    for (const c of clis) {
+      const section = el(`<fieldset><legend>${c.binary}</legend></fieldset>`);
+      const prefixes = el(`<pre>${c.allowedPrefixes.map(a => `${a.prefix.join(" ")}  ${a.confirm ? "[confirm]" : ""}${a.mutating ? "[mutating]" : ""}`).join("\n")}</pre>`);
+      section.appendChild(prefixes);
+      const whoami = document.createElement("div");
+      whoami.className = c.whoami.available ? (c.whoami.ok ? "status-ok" : "status-bad") : "muted";
+      whoami.textContent = c.whoami.available ? `auth whoami: ${c.whoami.output}` : "auth whoami: not available for this CLI";
+      section.appendChild(whoami);
+      out.appendChild(section);
+    }
+  } catch (e) { out.textContent = "error: " + e.message; }
+}
+
+// ---------- Model ----------
+function buildModelPanel() {
+  return el(`<section id="panel-Model" aria-hidden="true">
+    <div class="row"><button id="model-refresh">Refresh</button></div>
+    <pre id="model-status"></pre>
+    <h3>Self + dependency health</h3>
+    <pre id="health-status"></pre>
+  </section>`);
+}
+async function loadModel() {
+  const p = panel("Model");
+  if (!p.querySelector("#model-refresh").onclick) p.querySelector("#model-refresh").onclick = loadModel;
+  const modelOut = p.querySelector("#model-status");
+  const healthOut = p.querySelector("#health-status");
+  try {
+    const status = await api("/api/model/status");
+    modelOut.textContent = JSON.stringify(status, null, 2);
+  } catch (e) { modelOut.textContent = "error: " + e.message; }
+  try {
+    const health = await api("/api/health");
+    healthOut.textContent = JSON.stringify(health, null, 2);
+  } catch (e) { healthOut.textContent = "error: " + e.message; }
+}
+
+// ---------- System prompt ----------
+function buildSystemPromptPanel() {
+  return el(`<section id="panel-System prompt" aria-hidden="true">
+    <div class="row"><button id="sp-refresh">Refresh</button></div>
+    <h3>Terminal</h3>
+    <pre id="sp-terminal"></pre>
+    <h3>Google Chat</h3>
+    <pre id="sp-google"></pre>
+  </section>`);
+}
+async function loadSystemPrompt() {
+  const p = panel("System prompt");
+  if (!p.querySelector("#sp-refresh").onclick) p.querySelector("#sp-refresh").onclick = loadSystemPrompt;
+  try {
+    const data = await api("/api/system-prompt");
+    p.querySelector("#sp-terminal").textContent = data.terminal;
+    p.querySelector("#sp-google").textContent = data.googleChat;
+  } catch (e) { p.querySelector("#sp-terminal").textContent = "error: " + e.message; }
+}
+
+// ---------- Tool log ----------
+function buildToolLogPanel() {
+  return el(`<section id="panel-Tool log" aria-hidden="true">
+    <div class="row"><button id="log-refresh">Refresh</button></div>
+    <table>
+      <thead><tr><th>time</th><th>channel</th><th>tool</th><th>input</th><th>output</th></tr></thead>
+      <tbody id="log-body"></tbody>
+    </table>
+  </section>`);
+}
+async function loadToolLog() {
+  const p = panel("Tool log");
+  if (!p.querySelector("#log-refresh").onclick) p.querySelector("#log-refresh").onclick = loadToolLog;
+  const body = p.querySelector("#log-body");
+  body.innerHTML = "<tr><td colspan=5>loading...</td></tr>";
+  try {
+    const { entries } = await api("/api/tool-log");
+    body.innerHTML = "";
+    for (const e of entries) {
+      const tr = document.createElement("tr");
+      tr.innerHTML = `<td>${e.timestamp}</td><td>${e.channel}</td><td>${e.toolName}</td><td>${escapeHtml(e.input)}</td><td>${escapeHtml(e.output)}</td>`;
+      body.appendChild(tr);
+    }
+    if (!entries.length) body.innerHTML = "<tr><td colspan=5 class='muted'>(empty — run a turn that calls a tool)</td></tr>";
+  } catch (e) { body.innerHTML = `<tr><td colspan=5>error: ${e.message}</td></tr>`; }
+}
+function escapeHtml(s) {
+  const d = document.createElement("div");
+  d.textContent = s;
+  return d.innerHTML;
+}
+
+// ---------- Env ----------
+function buildEnvPanel() {
+  return el(`<section id="panel-Env" aria-hidden="true">
+    <p class="muted">Only these keys are ever read or written here — everything else in .env (including secrets) is never touched or listed.</p>
+    <div id="env-fields"></div>
+    <p class="muted">Saved to .env — run <code>docker compose up -d</code> to apply. No restart button here on purpose (a plain container restart doesn't reload .env — see plan).</p>
+  </section>`);
+}
+async function loadEnv() {
+  const p = panel("Env");
+  const fields = p.querySelector("#env-fields");
+  fields.textContent = "loading...";
+  try {
+    const [{ keys, values }, modelStatus] = await Promise.all([api("/api/env"), api("/api/model/status")]);
+    fields.innerHTML = "";
+    for (const key of keys) {
+      const row = document.createElement("div");
+      row.className = "row";
+      const label = document.createElement("label");
+      label.textContent = key;
+      label.style.width = "20rem";
+      row.appendChild(label);
+
+      let input;
+      if (key === "OLLAMA_MODEL") {
+        input = document.createElement("select");
+        for (const m of modelStatus.availableModels || []) {
+          const opt = document.createElement("option");
+          opt.value = m; opt.textContent = m;
+          if (m === values[key]) opt.selected = true;
+          input.appendChild(opt);
+        }
+        if (!modelStatus.availableModels) {
+          const opt = document.createElement("option");
+          opt.textContent = "(Ollama unreachable — can't list models)";
+          input.appendChild(opt);
+        }
+      } else {
+        input = document.createElement("input");
+        input.type = "number";
+        input.value = values[key] ?? "";
+      }
+      row.appendChild(input);
+
+      const saveBtn = document.createElement("button");
+      saveBtn.textContent = "Save";
+      saveBtn.onclick = async () => {
+        try {
+          await api("/api/env", { method: "PUT", headers: jsonHeaders, body: JSON.stringify({ key, value: String(input.value) }) });
+          saveBtn.textContent = "Saved";
+          setTimeout(() => (saveBtn.textContent = "Save"), 1500);
+        } catch (e) { alert("error: " + e.message); }
+      };
+      row.appendChild(saveBtn);
+      fields.appendChild(row);
+    }
+  } catch (e) { fields.textContent = "error: " + e.message; }
+}
+
+const jsonHeaders = { "content-type": "application/json" };
+
+const loaders = {
+  "Wiki": loadWikiList,
+  "CLI": loadCli,
+  "Model": loadModel,
+  "System prompt": loadSystemPrompt,
+  "Tool log": loadToolLog,
+  "Env": loadEnv,
+};
+
+panelsEl.appendChild(buildWikiPanel());
+panelsEl.appendChild(buildQdrantPanel());
+panelsEl.appendChild(buildCliPanel());
+panelsEl.appendChild(buildModelPanel());
+panelsEl.appendChild(buildSystemPromptPanel());
+panelsEl.appendChild(buildToolLogPanel());
+panelsEl.appendChild(buildEnvPanel());
+
+renderNav();
+showPanel(active);
+</script>
+</body>
+</html>

package/src/admin/qdrant-scroll.ts

@@ -0,0 +1,45 @@
+/**
+ * Read-only point enumeration for the admin panel's Qdrant inspection tab —
+ * `episodic-store.ts`/`semantic-facts-store.ts` only wrap similarity
+ * `search`, there's no existing way to just list what's in a collection.
+ * One page per call (not an auto-paging fetch-everything loop): a real
+ * collection can be arbitrarily large, so the caller decides whether to
+ * request another page via the returned `nextOffset`.
+ */
+// Matches @qdrant/js-client-rest's real ExtendedPointId-based offset type
+// (`string | number | Record<string, unknown> | null`) — a scroll offset
+// is an opaque cursor as far as this module is concerned, only ever
+// forwarded verbatim, but it has to line up with the real client's type
+// for a real `QdrantClient` instance to satisfy this structurally.
+type ScrollOffset = string | number | Record<string, unknown> | null;
+
+export type ScrollableQdrantClient = {
+  scroll(
+    collection: string,
+    params: { limit: number; offset?: ScrollOffset; with_payload: boolean },
+  ): Promise<{
+    points: Array<{ id: string | number; payload?: Record<string, unknown> | null }>;
+    next_page_offset?: ScrollOffset;
+  }>;
+};
+
+export type ScrollPage = {
+  points: Array<{ id: string | number; payload: Record<string, unknown> | null }>;
+  nextOffset: ScrollOffset;
+};
+
+export async function scrollCollection(
+  client: ScrollableQdrantClient,
+  collectionName: string,
+  opts: { limit: number; offset?: ScrollOffset },
+): Promise<ScrollPage> {
+  const result = await client.scroll(collectionName, {
+    limit: opts.limit,
+    offset: opts.offset,
+    with_payload: true,
+  });
+  return {
+    points: result.points.map((p) => ({ id: p.id, payload: p.payload ?? null })),
+    nextOffset: result.next_page_offset ?? null,
+  };
+}