@saadnvd1/agent-os 0.3.792 → 0.3.799

package/lib/chat/drivers/copilot-ask.ts

@@ -0,0 +1,232 @@
+import crypto from "node:crypto";
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import type { ChatQuestion } from "../events";
+import {
+  answersInOrder,
+  type ApprovalOutcome,
+  type PendingApprovals,
+} from "./pending-approvals";
+
+type P = Record<string, unknown>;
+const str = (v: unknown) => (typeof v === "string" ? v : "");
+
+export const ASK_SERVER = "agentos";
+export const ASK_TOOL = "ask_user";
+const MAX_BODY = 64 * 1024;
+
+// Copilot CLI doesn't offer its own ask_user over ACP, so each conversation
+// serves one: a question the agent asks becomes the chat's question card.
+export const askInput = {
+  question: z.string().min(1).describe("The question to show the user"),
+  options: z
+    .array(
+      z.object({
+        label: z.string().min(1),
+        description: z.string().optional(),
+      })
+    )
+    .optional()
+    .describe("Choices to offer; leave out for a free-text question"),
+  multiSelect: z
+    .boolean()
+    .optional()
+    .describe("Let the user pick more than one option"),
+  allowFreeText: z
+    .boolean()
+    .optional()
+    .describe("The user can always type their own answer too"),
+  header: z.string().optional().describe("A short label for the question"),
+};
+
+type AskArgs = {
+  question: string;
+  options?: { label: string; description?: string }[];
+  multiSelect?: boolean;
+  header?: string;
+};
+
+export function askUserQuestion(a: AskArgs): ChatQuestion {
+  const seen = new Set<string>();
+  const options = (a.options ?? []).flatMap((o) => {
+    const label = o.label.trim();
+    if (!label || seen.has(label)) return [];
+    seen.add(label);
+    return [{ label, description: o.description?.trim() ?? "" }];
+  });
+  return {
+    question: a.question.trim(),
+    header: a.header?.trim() ?? "",
+    multiSelect: !!a.multiSelect && options.length > 0,
+    options,
+  };
+}
+
+const text = (t: string, isError = false): CallToolResult => ({
+  content: [{ type: "text", text: t }],
+  ...(isError ? { isError } : {}),
+});
+
+export function askUserResult(
+  q: ChatQuestion,
+  o: ApprovalOutcome
+): CallToolResult {
+  if (o.decision === "answer") {
+    const [list] = answersInOrder([q], o.answers);
+    return text(
+      JSON.stringify(
+        q.multiSelect ? { answers: list } : { answer: list[0] ?? "" }
+      )
+    );
+  }
+  if (o.decision === "expired")
+    return text("The question was cancelled before the user answered.", true);
+  return text("The user skipped this question without answering.");
+}
+
+// Whether a Copilot tool call (a tool_call update or a permission request) is
+// our ask_user. Its title carries the server and tool name; the input is the
+// fallback for a title that doesn't.
+export function isAskUserCall(call: P): boolean {
+  const raw = (call.rawInput ?? {}) as P;
+  const title = str(call.title);
+  return (
+    title.includes(ASK_TOOL) ||
+    (title.includes(ASK_SERVER) && typeof raw.question === "string")
+  );
+}
+
+// One private MCP server per conversation: loopback only, behind a secret
+// path, so nothing else can reach it or answer its cards.
+export class CopilotAskServer {
+  private http?: http.Server;
+  private secret = crypto.randomBytes(32).toString("hex");
+  private next = 0;
+  private live = new Set<{ close(): Promise<void> }>();
+
+  constructor(private pending: PendingApprovals) {}
+
+  private build(): McpServer {
+    const server = new McpServer({ name: ASK_SERVER, version: "1.0.0" });
+    server.registerTool(
+      ASK_TOOL,
+      {
+        description:
+          "Ask the user a question and wait for the answer. Use it when you need a decision or missing information instead of asking in plain text. Offer options for a choice (multiSelect to allow several); with no options the user types an answer. Blocks until they answer.",
+        inputSchema: askInput,
+      },
+      async (args) => {
+        const q = askUserQuestion(args);
+        const o = await this.pending.ask({
+          id: `approval-ask-${++this.next}`,
+          toolName: "AskUserQuestion",
+          title: "Questions",
+          input: { questions: [q] },
+          questions: [q],
+          canAlways: false,
+        });
+        return askUserResult(q, o);
+      }
+    );
+    return server;
+  }
+
+  private allowed(req: http.IncomingMessage): number {
+    if (req.headers.origin) return 403;
+    const host = (req.headers.host ?? "").replace(/:\d+$/, "");
+    if (host !== "127.0.0.1" && host !== "localhost") return 403;
+    const want = Buffer.from(`/mcp/${this.secret}`);
+    const got = Buffer.from((req.url ?? "").split("?")[0]);
+    return got.length === want.length && crypto.timingSafeEqual(got, want)
+      ? 200
+      : 404;
+  }
+
+  private async handle(
+    req: http.IncomingMessage,
+    res: http.ServerResponse
+  ): Promise<void> {
+    const status = this.allowed(req);
+    if (status !== 200) {
+      res.writeHead(status).end();
+      return;
+    }
+    if (req.method !== "POST") {
+      res.writeHead(405, { allow: "POST" }).end();
+      return;
+    }
+    let size = 0;
+    const chunks: Buffer[] = [];
+    for await (const c of req) {
+      size += (c as Buffer).length;
+      if (size > MAX_BODY) {
+        res.writeHead(413).end();
+        return;
+      }
+      chunks.push(c as Buffer);
+    }
+    let body: unknown;
+    try {
+      body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    } catch {
+      res.writeHead(400).end();
+      return;
+    }
+    const server = this.build();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true,
+    });
+    const handle = {
+      close: async () => {
+        await transport.close();
+        await server.close();
+      },
+    };
+    this.live.add(handle);
+    res.on("close", () => {
+      this.live.delete(handle);
+      void handle.close().catch(() => {});
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, body);
+  }
+
+  // The `mcpServers` entry to give ACP session/new and session/load.
+  async start(): Promise<P> {
+    const server = http.createServer((req, res) => {
+      this.handle(req, res).catch(() => {
+        if (!res.headersSent) res.writeHead(500);
+        res.end();
+      });
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    this.http = server;
+    const { port } = server.address() as AddressInfo;
+    return {
+      type: "http",
+      name: ASK_SERVER,
+      url: `http://127.0.0.1:${port}/mcp/${this.secret}`,
+      headers: [],
+    };
+  }
+
+  // Cancels any question still waiting (its call returns a cancellation)
+  // and stops listening.
+  close(): void {
+    this.pending.expireAll();
+    const server = this.http;
+    this.http = undefined;
+    server?.close();
+    server?.closeAllConnections();
+    for (const h of this.live) void h.close().catch(() => {});
+    this.live.clear();
+  }
+}

package/lib/chat/drivers/copilot-mapper.ts

@@ -1,5 +1,6 @@
 import type { ChatContext, DriverEvent, UsageTotals } from "../events";
 import { toolTitle } from "../tools";
+import { isAskUserCall } from "./copilot-ask";
 import { TurnItems, type ToolStart } from "./turn-items";
 
 type P = Record<string, unknown>;
@@ -135,14 +136,22 @@ export class CopilotMapper {
     this.block++;
   }
 
+  // The card is the question's only trace, so its tool call stays hidden.
+  private asks = new Set<string>();
+
   private started(update: P): void {
     this.items.startTurn();
+    if (isAskUserCall(update)) {
+      this.asks.add(str(update.toolCallId));
+      return;
+    }
     this.close();
     this.items.tool(str(update.toolCallId), toolStart(update));
   }
 
   private updated(update: P): void {
     const id = str(update.toolCallId);
+    if (this.asks.has(id)) return;
     const status = str(update.status);
     if (status !== "completed" && status !== "failed") return;
     const start = toolStart(update);

package/lib/chat/drivers/copilot.ts

@@ -6,6 +6,7 @@ import type { ChatConversation, ChatDriver, ChatStartOptions } from "../driver";
 import type { ChatImage, ChatModel, DriverEvent } from "../events";
 import { InputQueue } from "../queue";
 import { AGENT_DEFAULT_MODEL } from "../../providers/registry";
+import { ASK_SERVER, ASK_TOOL, CopilotAskServer } from "./copilot-ask";
 import { CopilotApprovals } from "./copilot-approvals";
 import { CopilotMapper } from "./copilot-mapper";
 import { CopilotRpc } from "./copilot-rpc";
@@ -33,7 +34,10 @@ export function copilotArgs(
   fallback = copilotDefaultModel({ ...process.env, ...o.env })
 ): string[] {
   const model = o.model && o.model !== AGENT_DEFAULT_MODEL ? o.model : fallback;
-  return model ? ["--model", model] : [];
+  return [
+    ...(model ? ["--model", model] : []),
+    `--allow-tool=${ASK_SERVER}(${ASK_TOOL})`,
+  ];
 }
 
 // The models a new ACP session offers (`models.availableModels`), with
@@ -117,6 +121,7 @@ export const copilotDriver: ChatDriver = {
     const emit = (e: DriverEvent) => out.push(e);
     const mapper = new CopilotMapper(emit);
     const approvals = new CopilotApprovals(emit, options.access);
+    const ask = new CopilotAskServer(approvals.pending);
     let sessionId: string | null = null;
     let busy = false;
     let intro = options.resumeId ? "" : (options.systemAppend ?? "").trim();
@@ -136,7 +141,7 @@ export const copilotDriver: ChatDriver = {
           void approvals.handle(params).then((result) => rpc.reply(id, result));
         },
         exit(error) {
-          approvals.pending.expireAll();
+          ask.close();
           mapper.endTurn({ error });
           out.end();
         },
@@ -145,7 +150,15 @@ export const copilotDriver: ChatDriver = {
     emit({ type: "usage_start", totals: { ...mapper.totals } });
 
     const ready = rpc.initialize().then(async () => {
-      const params = { cwd: options.cwd, mcpServers: [] };
+      // Without it the agent just can't ask: the chat still works.
+      const mcpServers = await ask.start().then(
+        (s) => [s],
+        (e: Error) => {
+          mapper.items.error(`Questions aren't available: ${e.message}`);
+          return [];
+        }
+      );
+      const params = { cwd: options.cwd, mcpServers };
       if (options.resumeId) {
         mapper.replaying = true;
         try {
@@ -170,6 +183,7 @@ export const copilotDriver: ChatDriver = {
       emit({ type: "resume_id", id: sessionId });
     });
     ready.catch((error: Error) => {
+      ask.close();
       mapper.items.error(`GitHub Copilot couldn't start: ${error.message}`);
       mapper.endTurn({});
       out.end();
@@ -243,7 +257,7 @@ export const copilotDriver: ChatDriver = {
         };
       },
       close() {
-        approvals.pending.expireAll();
+        ask.close();
         rpc.close();
         out.end();
       },

package/lib/db/migrations.ts

@@ -26,6 +26,11 @@ export type { Migration } from "./migration-types";
 // typecheck, lint and test) and is not committed. A duplicate id or key, or a
 // file whose name does not match its id, throws when this module loads.
 // lib/db/migrations.test.ts enforces the rest.
+//
+// A migration must leave the previous release runnable: an automatic update
+// that isn't healthy rolls the code back but not the database (chat workers
+// keep writing through the restart, so a restore would drop their work). Add
+// columns and tables; don't rename or drop what the last release reads.
 
 export const migrationKey = (m: Migration): string => m.key ?? String(m.id);
 const migrationName = (m: Migration): string =>
@@ -93,6 +98,22 @@ function compareToUpTo(m: Migration, upTo: number | string): number {
 // All migrations in order - never modify existing ones, only add new
 export const migrations: Migration[] = buildRegistry(migrationFiles);
 
+/** How many of this build's migrations the database has; the update health check reads it. */
+export function migrationStatus(db: Database.Database): {
+  known: number;
+  applied: number;
+} {
+  const rows = db.prepare(`SELECT id, key FROM _migrations`).all() as {
+    id: number;
+    key: string | null;
+  }[];
+  const have = new Set(rows.map((r) => r.key ?? String(r.id)));
+  return {
+    known: migrations.length,
+    applied: migrations.filter((m) => have.has(migrationKey(m))).length,
+  };
+}
+
 // `upTo`: stop after this legacy id or timestamp key, inclusive (tests that
 // start from an older database).
 export function runMigrations(

package/lib/recipes/timer.ts

@@ -67,7 +67,9 @@ export function setTimer(
   if (!isTimezone(timezone)) throw new Error(`Unknown time zone "${timezone}"`);
   const bad = cronError(cron);
   if (bad) throw new Error(bad);
-  if (minGapMinutes(cron, timezone) < MIN_GAP_MINUTES)
+  if (
+    minGapMinutes(cron, timezone, Date.now(), MIN_GAP_MINUTES) < MIN_GAP_MINUTES
+  )
     throw new Error("A recipe runs at most once an hour");
   const enabled = input.enabled ?? true;
   if (!existing) {

package/lib/schedules/cron.ts

@@ -261,16 +261,25 @@ export const MIN_GAP_MINUTES = 60;
 // A message to a session, at most this often.
 export const MESSAGE_MIN_GAP_MINUTES = 10;
 
-// The shortest gap between runs over the next few weeks of them.
+// The shortest gap between runs over the next few weeks of them. With
+// `stopBelow`, it returns as soon as a gap under it turns up: "every minute"
+// then costs two searches, not two hundred.
 export function minGapMinutes(
   cron: string,
   timezone: string,
-  from = Date.now()
+  from = Date.now(),
+  stopBelow = 0
 ): number {
-  const runs = nextRuns(cron, from, 200, timezone);
+  const parsed = parseCron(cron);
   let min = Infinity;
-  for (let i = 1; i < runs.length; i++)
-    min = Math.min(min, (runs[i] - runs[i - 1]) / 60_000);
+  let prev = nextRun(parsed, from, timezone);
+  for (let i = 1; i < 200 && prev !== null; i++) {
+    const next = nextRun(parsed, prev, timezone);
+    if (next === null) break;
+    min = Math.min(min, (next - prev) / 60_000);
+    if (min < stopBelow) break;
+    prev = next;
+  }
   return min;
 }
 

package/lib/schedules/store.ts

@@ -298,7 +298,7 @@ function validate(
   if (
     !oneOff &&
     (input.kind === "task" || input.kind === "session") &&
-    minGapMinutes(cron, timezone) < MIN_GAP_MINUTES
+    minGapMinutes(cron, timezone, Date.now(), MIN_GAP_MINUTES) < MIN_GAP_MINUTES
   )
     throw new Error(
       "A task or session schedule runs at most once an hour; for more often, post to the orchestrator"
@@ -309,7 +309,8 @@ function validate(
   if (
     !oneOff &&
     (message || agentCheckIn) &&
-    minGapMinutes(cron, timezone) < MESSAGE_MIN_GAP_MINUTES
+    minGapMinutes(cron, timezone, Date.now(), MESSAGE_MIN_GAP_MINUTES) <
+      MESSAGE_MIN_GAP_MINUTES
   )
     throw new Error(
       `A message schedule runs at most every ${MESSAGE_MIN_GAP_MINUTES} minutes`

package/lib/security/demo.ts

@@ -150,6 +150,8 @@ const READS = [
   "demo",
   // The changelog: a static file, no agent.
   "whats-new",
+  // Tip of the Day: reading is a static file plus two settings.
+  "tips",
 ].map(route);
 
 // The only writes, each a database write and nothing more in demo mode:

package/lib/tasks/finish.ts

@@ -88,17 +88,17 @@ async function cleanup(
   forgetPR(session.id);
 }
 
-// Sign-offs between `gh pr merge` and the database knowing it, so the
-// watcher doesn't read our own merge as one done on GitHub.
-export const signingOff = new Set<string>();
-
 // What happens after a merge: restack anything stacked on it, then remove the
 // session, worktree and branch. Kept per task so Land and done can wait for
 // it; on globalThis because the watcher's merges run in server.ts and done in
-// a route bundle, which load this module separately.
+// a route bundle, which load this module separately. lib/busy.ts counts both.
 const g = globalThis as unknown as {
   __agentosAfterMerge?: Map<string, Promise<void>>;
+  __agentosSigningOff?: Set<string>;
 };
+// Sign-offs between `gh pr merge` and the database knowing it, so the
+// watcher doesn't read our own merge as one done on GitHub.
+export const signingOff: Set<string> = (g.__agentosSigningOff ??= new Set());
 const afterMerge: Map<string, Promise<void>> = (g.__agentosAfterMerge ??=
   new Map());
 

package/lib/tips/conditions.ts

@@ -0,0 +1,38 @@
+import { readConnect } from "@/lib/connect/config";
+import { listBookmarks } from "@/lib/bookmarks/store";
+import { listRecipes } from "@/lib/recipes/store";
+import { listSchedules } from "@/lib/schedules/store";
+import { listDevices } from "@/lib/security/devices";
+import { listGroups } from "@/lib/session-groups/store";
+import { listSharedLinks } from "@/lib/share/store";
+import type { Condition, Tip } from "./schema";
+
+const CHECKS: Record<Condition, () => boolean> = {
+  "no-paired-device": () => listDevices().length === 0,
+  "no-push-device": () => !listDevices().some((d) => d.push.enabled),
+  "connect-not-linked": () => !readConnect().ok,
+  "connect-linked": () => {
+    const c = readConnect();
+    return c.ok && c.enabled;
+  },
+  "no-schedules": () => listSchedules().length === 0,
+  "no-recipes": () => listRecipes().length === 0,
+  "no-shares": () => listSharedLinks().length === 0,
+  "no-groups": () => listGroups().length === 0,
+  "no-bookmarks": () =>
+    listBookmarks({ workspace: "all", limit: 1 }).bookmarks.length === 0,
+};
+
+/** Whether the tip applies now; a check that throws counts as no. */
+export function tipApplies(
+  tip: Pick<Tip, "when">,
+  checks: Record<string, () => boolean> = CHECKS
+): boolean {
+  return (tip.when ?? []).every((c) => {
+    try {
+      return checks[c]?.() ?? false;
+    } catch {
+      return false;
+    }
+  });
+}

package/lib/tips/index.ts

@@ -0,0 +1,2 @@
+export { markSeen, setTipsOff, tipsView } from "./view";
+export type { ClientTip, Media, Tip, TipsView } from "./schema";

package/lib/tips/load.ts

@@ -0,0 +1,26 @@
+import fs from "fs";
+import path from "path";
+import { fileSchema, type Tip } from "./schema";
+
+export const TIPS_FILE = "content/tips.json";
+
+let cached: { file: string; mtime: number; tips: Tip[] } | null = null;
+
+/** Every tip that isn't retired. A missing or unreadable file is empty. */
+export function loadTips(root: string = process.cwd()): Tip[] {
+  const file = path.join(root, TIPS_FILE);
+  try {
+    const mtime = fs.statSync(file).mtimeMs;
+    if (cached?.file === file && cached.mtime === mtime) return cached.tips;
+    const parsed = fileSchema.safeParse(
+      JSON.parse(fs.readFileSync(file, "utf-8"))
+    );
+    const tips = parsed.success
+      ? parsed.data.tips.filter((t) => !t.hidden)
+      : [];
+    cached = { file, mtime, tips };
+    return tips;
+  } catch {
+    return [];
+  }
+}

package/lib/tips/media.ts

@@ -0,0 +1,101 @@
+import fs from "fs";
+import path from "path";
+import { fileSchema, type Media, type MediaBrief, type Tip } from "./schema";
+
+export const MEDIA_DIR = "public/tips";
+export const BUDGET = {
+  still: 90 * 1024,
+  clip: 500 * 1024,
+  poster: 40 * 1024,
+  total: 6 * 1024 * 1024,
+  clipSeconds: 8,
+  width: 768,
+} as const;
+
+/** The files a media value points at, as names inside public/tips. */
+export function mediaFiles(m: Media): { name: string; max: number }[] {
+  const name = (src: string) => path.basename(src);
+  return m.kind === "image"
+    ? [
+        { name: name(m.src), max: BUDGET.still },
+        ...(m.srcDark ? [{ name: name(m.srcDark), max: BUDGET.still }] : []),
+      ]
+    : [
+        { name: name(m.src), max: BUDGET.clip },
+        { name: name(m.poster), max: BUDGET.poster },
+      ];
+}
+
+export interface ManifestRow {
+  id: string;
+  title: string;
+  kind: MediaBrief["kind"];
+  shot: string;
+  theme: NonNullable<MediaBrief["theme"]>;
+  guide?: string;
+  target: { width: number; maxBytes: number; maxSeconds?: number };
+  dest: string;
+}
+
+/** What Luna still has to make: tips with a brief and no media yet. */
+export function manifest(tips: Tip[]): ManifestRow[] {
+  return tips
+    .filter((t) => t.mediaBrief && !t.media)
+    .map((t) => {
+      const b = t.mediaBrief!;
+      const clip = b.kind === "clip";
+      return {
+        id: t.id,
+        title: t.title,
+        kind: b.kind,
+        shot: b.shot,
+        theme: b.theme ?? (clip ? "dark" : "both"),
+        ...(t.guide && { guide: t.guide.file }),
+        target: {
+          width: BUDGET.width,
+          maxBytes: clip ? BUDGET.clip : BUDGET.still,
+          ...(clip && { maxSeconds: BUDGET.clipSeconds }),
+        },
+        dest: `${MEDIA_DIR}/${t.id}.${clip ? "mp4" : "webp"}`,
+      };
+    });
+}
+
+/**
+ * Copies the finished files from `from` into `root`/public/tips and writes each
+ * tip's `media` (dropping its brief). Throws before changing anything if an id
+ * is unknown, a file is missing, or a file is over its budget.
+ */
+export function applyHandback(
+  root: string,
+  from: string,
+  handback: Record<string, Media>
+): string[] {
+  const file = path.join(root, "content/tips.json");
+  const parsed = fileSchema.parse(JSON.parse(fs.readFileSync(file, "utf-8")));
+  const copies: [string, string][] = [];
+  for (const [id, media] of Object.entries(handback)) {
+    if (!parsed.tips.some((t) => t.id === id))
+      throw new Error(`Unknown tip "${id}"`);
+    for (const { name, max } of mediaFiles(media)) {
+      const src = path.join(from, name);
+      if (!fs.existsSync(src)) throw new Error(`${id}: ${name} is missing`);
+      const size = fs.statSync(src).size;
+      if (size > max)
+        throw new Error(`${id}: ${name} is ${size} bytes, over ${max}`);
+      copies.push([src, path.join(root, MEDIA_DIR, name)]);
+    }
+    if (media.kind === "video" && media.durationMs > BUDGET.clipSeconds * 1000)
+      throw new Error(`${id}: clip is longer than ${BUDGET.clipSeconds}s`);
+  }
+  fs.mkdirSync(path.join(root, MEDIA_DIR), { recursive: true });
+  for (const [a, b] of copies) fs.copyFileSync(a, b);
+  const tips = parsed.tips.map((t) => {
+    const media = handback[t.id];
+    if (!media) return t;
+    const { mediaBrief: _brief, ...rest } = t;
+    return { ...rest, media };
+  });
+  fs.writeFileSync(file, JSON.stringify({ ...parsed, tips }, null, 2) + "\n");
+  return Object.keys(handback);
+}

package/lib/tips/pick.ts

@@ -0,0 +1,35 @@
+import type { Tip } from "./schema";
+
+export interface Pinned {
+  day: string;
+  id: string;
+  read: boolean;
+}
+
+/** Newest first; tips added the same day keep the order they have in the file. */
+export const orderDeck = <T extends Pick<Tip, "id" | "added">>(
+  tips: T[]
+): T[] =>
+  [...tips].sort((a, b) =>
+    a.added === b.added ? 0 : a.added < b.added ? 1 : -1
+  );
+
+/**
+ * The tip for `day`: the one already chosen today while it still applies,
+ * else the first the user hasn't seen, else (all seen) the one seen longest ago.
+ */
+export function pickToday(o: {
+  deck: { id: string }[];
+  seen: Record<string, string>;
+  pinned: Pinned | null;
+  day: string;
+}): Pinned | null {
+  const { deck, seen, pinned, day } = o;
+  if (!deck.length) return null;
+  if (pinned?.day === day && deck.some((t) => t.id === pinned.id))
+    return pinned;
+  const fresh = deck.find((t) => !seen[t.id]);
+  if (fresh) return { day, id: fresh.id, read: false };
+  const oldest = deck.reduce((a, b) => (seen[b.id] < seen[a.id] ? b : a));
+  return { day, id: oldest.id, read: false };
+}