@andrioid/paseo-attention-span 0.0.0-stage → 0.1.0

package/server/service.ts

@@ -0,0 +1,248 @@
+import type { Attention, AttentionView, FeedId, FeedStatus, Item } from "../shared/attention";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import { AttentionConfig, githubRepoOf } from "../shared/config";
+import { classify, classifyHistory } from "./classify";
+import { FIXTURE, graphql } from "./gh";
+import { fixture, FIXTURE_AGENTS } from "./fixture";
+import type { Details, HistoryResult, LiveResult } from "./github-types";
+import { detailsQuery, HISTORY_SEARCHES, LIVE_SEARCHES, type SearchName, searchQuery, searchVariables, unclaimedScope } from "./queries";
+import { loadConfig, loadState, moveOldFiles, saveCodeRepo, saveCoverage, saveState, State } from "./store";
+import { buildView } from "./view";
+
+// History changes only when I finish something, so it's fetched daily, on ⟳ in its tab and after a merge.
+const HISTORY_MAX_AGE_SECONDS = 24 * 60 * 60;
+// A failed refresh is retried at most this often, except on ⟳.
+const RETRY_MS = 5 * 60_000;
+
+interface Feed {
+  inFlight: Promise<void> | null;
+  lastAttemptAt: number;
+  error: string | null;
+}
+
+// Owns the cache and the background refresh of each feed [FRESH-01, PRIV-01].
+export class AttentionService {
+  private state: State = State.parse({});
+  private config: AttentionConfig = AttentionConfig.parse({});
+  private configError: string | null = null;
+  private feeds: Record<FeedId, Feed> = {
+    live: { inFlight: null, lastAttemptAt: 0, error: null },
+    history: { inFlight: null, lastAttemptAt: 0, error: null },
+  };
+  private saving: Promise<void> = Promise.resolve();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private intervalMinutes = 0;
+  // The app's connection to Paseo, from its last request; background refreshes have none of their own.
+  private paseo: PluginHandlerContext["paseo"] | null = null;
+
+  async start(): Promise<void> {
+    await moveOldFiles().catch((error) => console.error("Couldn't move the old settings folder:", error));
+    this.state = await loadState();
+    await this.reloadConfig().catch(() => {}); // shown as the screen's error
+    this.schedule();
+    void this.refreshStale();
+  }
+
+  connect(paseo: PluginHandlerContext["paseo"]): void {
+    this.paseo = paseo;
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  // ⟳ fetches its tab's feed now; otherwise feeds older than their schedule are fetched first.
+  async get(refresh?: FeedId): Promise<AttentionView> {
+    if (refresh) await this.refresh(refresh).catch(() => {});
+    else await this.refreshStale();
+    return this.view();
+  }
+
+  async dismiss(key: string): Promise<AttentionView> {
+    const item = this.items().find((candidate) => candidate.key === key);
+    if (item) {
+      this.state.dismissed[key] = { at: item.othersActivityAt, section: item.section };
+      await this.save();
+    }
+    return this.view();
+  }
+
+  async undismiss(key: string): Promise<AttentionView> {
+    delete this.state.dismissed[key];
+    await saveState(this.state);
+    return this.view();
+  }
+
+  async restoreDismissed(): Promise<AttentionView> {
+    this.state.dismissed = {};
+    await this.save();
+    return this.view();
+  }
+
+  // Remember where an issue repo's code lives [SES-07].
+  async setCodeRepo(issueRepo: string, codeRepo: string): Promise<AttentionView> {
+    this.config = await saveCodeRepo(issueRepo, codeRepo);
+    return this.view();
+  }
+
+  // Orgs and repos chosen in settings [SRC-02]. The lists follow right away; History catches up behind them.
+  async setCoverage(orgs: string[], repos: string[]): Promise<void> {
+    this.config = await saveCoverage(orgs, repos);
+    void this.refresh("history").catch(() => {});
+    await this.refresh("live").catch(() => {});
+  }
+
+  async setScopes(scopes: string[]): Promise<void> {
+    this.state.scopes = scopes;
+    await this.save();
+  }
+
+  // Concurrent callers share one refresh per feed.
+  refresh(id: FeedId): Promise<void> {
+    const feed = this.feeds[id];
+    feed.inFlight ??= this.fetch(id).finally(() => (feed.inFlight = null));
+    return feed.inFlight;
+  }
+
+  private refreshStale(): Promise<unknown> {
+    const stale = (["live", "history"] as const).filter((id) => this.isStale(id));
+    return Promise.all(stale.map((id) => this.refresh(id).catch(() => {})));
+  }
+
+  private async fetch(id: FeedId): Promise<void> {
+    const feed = this.feeds[id];
+    feed.lastAttemptAt = Date.now();
+    try {
+      await this.reloadConfig();
+      const now = new Date();
+      const fetchedAt = now.toISOString();
+      if (id === "live") this.state.live = { fetchedAt, attention: await this.fetchLive(now) };
+      else this.state.history = { fetchedAt, items: await this.fetchHistory(now) };
+      // Forget dismissals of items that are gone.
+      const keys = new Set(this.items().map((item) => item.key));
+      for (const key of Object.keys(this.state.dismissed)) if (!keys.has(key)) delete this.state.dismissed[key];
+      feed.error = null;
+      await this.save();
+    } catch (error) {
+      feed.error = (error as Error).message;
+      console.error(`Attention Span ${id} refresh failed:`, feed.error);
+      throw error;
+    }
+  }
+
+  private async fetchLive(now: Date): Promise<Attention> {
+    const projectRepos = FIXTURE ? [] : await this.projectRepos();
+    const { data, details } = FIXTURE ? fixture(now) : await this.searchLive(now, projectRepos);
+    return { ...classify({ data, details, config: this.config, now }), unclaimedFrom: unclaimedScope(this.config, projectRepos).from };
+  }
+
+  // My Paseo projects' GitHub repos, where Next up looks when no repos are chosen [NXT-08].
+  // Without a connection yet, or if listing fails, the last list is used.
+  private async projectRepos(): Promise<string[]> {
+    if (this.paseo) {
+      try {
+        const { projects } = await this.paseo.projects.list();
+        this.state.projectRepos = [...new Set(projects.map((project) => githubRepoOf(project.projectKey)).filter((repo): repo is string => !!repo))].sort();
+      } catch (error) {
+        console.error("Couldn't list Paseo projects:", error);
+      }
+    }
+    return this.state.projectRepos;
+  }
+
+  private async fetchHistory(now: Date): Promise<Item[]> {
+    if (FIXTURE) return classifyHistory(fixture(now).data);
+    return classifyHistory(await graphql<HistoryResult>(searchQuery(HISTORY_SEARCHES), this.variables(HISTORY_SEARCHES, now)));
+  }
+
+  // One request per search, in parallel. The details request starts once the searches it needs are back [GH-01].
+  private async searchLive(now: Date, projectRepos: string[]): Promise<{ data: LiveResult; details: Details }> {
+    const all = searchVariables(this.config, now, projectRepos);
+    const search = async (name: (typeof LIVE_SEARCHES)[number]): Promise<Partial<LiveResult>> =>
+      all[name] === null ? { [name]: { nodes: [] } } : graphql<Partial<LiveResult>>(searchQuery([name], name === "mine"), { [name]: all[name] });
+    const merge = (parts: Partial<LiveResult>[]) => Object.assign({}, ...parts) as LiveResult;
+    const forDetails = Promise.all([search("mine"), search("assigned"), search("unclaimed")]);
+    const others = Promise.all([search("reviews"), search("mentions"), search("commented")]);
+    const afterThem = forDetails.then((parts) => this.details(merge(parts)));
+    const [first, rest, details] = await Promise.all([forDetails, others, afterThem]);
+    return { data: merge([...first, ...rest]), details };
+  }
+
+  private variables(names: readonly SearchName[], now: Date): Record<string, string | null> {
+    const all = searchVariables(this.config, now);
+    return Object.fromEntries(names.map((name) => [name, all[name]]));
+  }
+
+  // Behind counts [UPS-07] and issue field option order [NXT-02].
+  private async details(data: Pick<LiveResult, "mine" | "assigned" | "unclaimed">): Promise<Details> {
+    const prs = data.mine.nodes.filter((pr) => pr?.headRefName && !pr.isCrossRepository);
+    const { priority, effort } = this.config.nextUp;
+    const needsOptions = [priority, effort].some((field) => field && !field.order);
+    const issues = [...data.unclaimed.nodes, ...data.assigned.nodes];
+    const orgs = needsOptions ? [...new Set(issues.map((issue) => issue?.repository?.nameWithOwner.split("/")[0]).filter(Boolean))] : [];
+    const details: Details = { behind: {}, fieldOptions: {} };
+    if (prs.length === 0 && orgs.length === 0) return details;
+    const { query, compares } = detailsQuery(prs, orgs as string[]);
+    type Result = { ref?: { compare: { behindBy: number } | null } | null; issueFields?: { nodes: { name?: string; options?: { name: string }[] }[] } } | null;
+    const result = await graphql<Record<string, Result>>(query);
+    for (const [alias, value] of Object.entries(result)) {
+      const behindBy = value?.ref?.compare?.behindBy;
+      if (typeof behindBy === "number") details.behind[compares[alias]] = behindBy;
+      for (const field of value?.issueFields?.nodes ?? []) if (field.name && field.options) details.fieldOptions[field.name] ??= field.options.map((o) => o.name);
+    }
+    return details;
+  }
+
+  private async reloadConfig(): Promise<void> {
+    try {
+      this.config = await loadConfig();
+      this.configError = null;
+    } catch (error) {
+      this.configError = (error as Error).message;
+      throw error;
+    }
+    if (this.timer && this.intervalMinutes !== this.config.refreshMinutes) this.schedule();
+  }
+
+  private schedule(): void {
+    this.stop();
+    this.intervalMinutes = this.config.refreshMinutes;
+    this.timer = setInterval(() => {
+      void this.refresh("live").catch(() => {});
+      if (this.isStale("history")) void this.refresh("history").catch(() => {});
+    }, this.intervalMinutes * 60_000);
+  }
+
+  // Older than the feed's schedule, and not failed within the last few minutes.
+  private isStale(id: FeedId): boolean {
+    const maxAgeSeconds = id === "live" ? this.config.refreshMinutes * 60 : HISTORY_MAX_AGE_SECONDS;
+    const fetchedAt = this.state[id]?.fetchedAt;
+    const old = !fetchedAt || Date.now() - new Date(fetchedAt).getTime() >= maxAgeSeconds * 1000;
+    return old && Date.now() - this.feeds[id].lastAttemptAt >= RETRY_MS;
+  }
+
+  private items(): Item[] {
+    return [...(this.state.live?.attention.items ?? []), ...(this.state.history?.items ?? [])];
+  }
+
+  // Feeds finish independently; saves go one at a time so an older snapshot never lands last.
+  private save(): Promise<void> {
+    this.saving = this.saving.catch(() => {}).then(() => saveState(this.state));
+    return this.saving;
+  }
+
+  private view(): AttentionView {
+    const status = (id: FeedId): FeedStatus => ({
+      fetchedAt: this.state[id]?.fetchedAt ?? null,
+      refreshing: this.feeds[id].inFlight !== null,
+      error: this.feeds[id].error ?? this.configError,
+    });
+    return buildView(this.state.live?.attention ?? null, this.state.history?.items ?? [], this.state.dismissed, {
+      feeds: { live: status("live"), history: status("history") },
+      scopes: this.state.scopes,
+      config: this.config,
+      ...(FIXTURE ? { fixtureAgents: FIXTURE_AGENTS } : {}),
+    });
+  }
+}

package/server/setup.ts

@@ -0,0 +1,47 @@
+import type { ConfigStatus, CoverageCheck, CoverageKind, SetupStatus } from "../shared/setup";
+import { FIXTURE_ORGS, FIXTURE_REPOS } from "./fixture";
+import { FIXTURE, runGh } from "./gh";
+import { loadConfig } from "./store";
+
+// What the setup checklist needs [SET-01]. Asked only when Attention Span can't load.
+export async function setupStatus(): Promise<SetupStatus> {
+  return { gh: FIXTURE ? { found: true, login: "me", error: null } : await ghStatus(), config: await configStatus() };
+}
+
+// `gh api user` answers both questions at once: is gh there, and who is it signed in as.
+async function ghStatus(): Promise<SetupStatus["gh"]> {
+  try {
+    const { code, stdout, stderr } = await runGh(["api", "user", "--jq", ".login"]);
+    const login = stdout.trim();
+    return code === 0 && login ? { found: true, login, error: null } : { found: true, login: null, error: stderr.trim() || `gh exited with ${code}` };
+  } catch (error) {
+    return { found: false, login: null, error: (error as Error).message };
+  }
+}
+
+export async function configStatus(): Promise<ConfigStatus> {
+  try {
+    const { orgs, repos } = await loadConfig();
+    return { error: null, orgs, repos };
+  } catch (error) {
+    return { error: (error as Error).message, orgs: [], repos: [] };
+  }
+}
+
+// An org or repo is checked on GitHub before it's saved, so a typo shows right away [SRC-02].
+// Pasted GitHub URLs are accepted. The exact name GitHub returns is what gets saved.
+export async function checkCoverage(kind: CoverageKind, input: string): Promise<CoverageCheck> {
+  const name = input.trim().replace(/^(https?:\/\/)?github\.com\//i, "").replace(/\/+$/, "");
+  if (kind === "org" && !/^[\w.-]+$/.test(name)) return { name: null, error: "Use the organization's name, like acme" };
+  if (kind === "repo" && !/^[\w.-]+\/[\w.-]+$/.test(name)) return { name: null, error: "Use owner/name, like acme/shop" };
+  if (FIXTURE) {
+    const known = (kind === "org" ? FIXTURE_ORGS : FIXTURE_REPOS).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+    return known ? { name: known, error: null } : { name: null, error: `${name} wasn't found on GitHub` };
+  }
+  const { code, stdout, stderr } = await runGh(["api", kind === "org" ? `users/${name}` : `repos/${name}`, "--jq", kind === "org" ? ".login + \" \" + .type" : ".full_name"]);
+  if (code !== 0) return { name: null, error: /404|Not Found/i.test(stderr) ? `${name} wasn't found on GitHub, or gh's account can't see it` : stderr.trim() || `gh exited with ${code}` };
+  if (kind === "repo") return { name: stdout.trim(), error: null };
+  // Searches use org:, which matches organizations only.
+  const [login, type] = stdout.trim().split(" ");
+  return type === "Organization" ? { name: login, error: null } : { name: null, error: `${login} is a person, not an organization. Add their repos instead` };
+}

package/server/store.ts

@@ -0,0 +1,99 @@
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import type { Attention, Item, SectionId } from "../shared/attention";
+import { AttentionConfig } from "../shared/config";
+
+// Local files in ~/.config/paseo-attention-span/ [PRIV-01].
+const CHOSEN_DIR = process.env.PASEO_ATTENTION_SPAN_DIR ?? process.env.PASEO_GITHUB_ATTENTION_DIR;
+export const DIR = CHOSEN_DIR ?? join(homedir(), ".config", "paseo-attention-span");
+// Where they lived while the plugin was called "GitHub attention".
+const OLD_DIR = join(homedir(), ".config", "paseo-github-attention");
+const CONFIG = join(DIR, "config.json");
+const STATE = join(DIR, "state.json");
+
+export const State = z.object({
+  // Item key -> others' activity and section when dismissed [ATT-08].
+  dismissed: z.record(z.string(), z.object({ at: z.string(), section: z.custom<SectionId>() })).default({}),
+  // Scope chips picked on Next up; none means all [NXT-03].
+  scopes: z.array(z.string()).default([]),
+  // My Paseo projects' GitHub repos when last listed, for refreshes before the app has connected [NXT-08].
+  projectRepos: z.array(z.string()).default([]),
+  // The last fetch of each feed. A cache from an older version is dropped rather than shown wrong.
+  live: z.object({ fetchedAt: z.string(), attention: z.custom<Attention>((value) => Array.isArray((value as Attention)?.unclaimed)) }).nullable().catch(null),
+  history: z.object({ fetchedAt: z.string(), items: z.custom<Item[]>(Array.isArray) }).nullable().catch(null),
+});
+export type State = z.infer<typeof State>;
+
+// Moves the old folder over once, unless a folder is chosen by environment variable.
+export async function moveOldFiles(): Promise<void> {
+  if (CHOSEN_DIR || (await exists(DIR)) || !(await exists(OLD_DIR))) return;
+  await rename(OLD_DIR, DIR);
+}
+
+async function exists(path: string): Promise<boolean> {
+  return stat(path).then(
+    () => true,
+    () => false,
+  );
+}
+
+async function readJson(path: string): Promise<unknown> {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw new Error(`Can't read ${path}: ${(error as Error).message}`);
+  }
+}
+
+export async function loadConfig(): Promise<AttentionConfig> {
+  const parsed = AttentionConfig.safeParse(await readJson(CONFIG));
+  if (!parsed.success) throw new Error(`${CONFIG} is invalid: ${parsed.error.message}`);
+  return parsed.data;
+}
+
+// Where an issue repo's code lives, chosen on the screen [SES-07].
+export function saveCodeRepo(issueRepo: string, codeRepo: string): Promise<AttentionConfig> {
+  return updateConfig((file) => {
+    const existing = file.codeRepos && typeof file.codeRepos === "object" ? (file.codeRepos as Record<string, unknown>) : {};
+    const codeRepos = Object.fromEntries(Object.entries(existing).filter(([issues]) => issues.toLowerCase() !== issueRepo.toLowerCase()));
+    return { ...file, codeRepos: { ...codeRepos, [issueRepo]: codeRepo } };
+  });
+}
+
+// The orgs and repos chosen in settings [SRC-02].
+export function saveCoverage(orgs: string[], repos: string[]): Promise<AttentionConfig> {
+  return updateConfig((file) => ({ ...file, orgs, repos }));
+}
+
+// What the screen writes changes only its own keys; everything else in the file is kept as it is.
+// A file that doesn't read or parse is left alone.
+async function updateConfig(change: (file: Record<string, unknown>) => Record<string, unknown>): Promise<AttentionConfig> {
+  const raw = await readJson(CONFIG);
+  const current = AttentionConfig.safeParse(raw);
+  if (!current.success) throw new Error(`${CONFIG} is invalid: ${current.error.message}`);
+  const next = change(raw as Record<string, unknown>);
+  const parsed = AttentionConfig.safeParse(next);
+  if (!parsed.success) throw new Error(`${CONFIG} is invalid: ${parsed.error.message}`);
+  await writeAtomically(CONFIG, `${JSON.stringify(next, null, 2)}\n`);
+  return parsed.data;
+}
+
+async function writeAtomically(path: string, content: string): Promise<void> {
+  await mkdir(DIR, { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, content);
+  await rename(temporary, path);
+}
+
+export async function loadState(): Promise<State> {
+  const parsed = State.safeParse(await readJson(STATE).catch(() => ({})));
+  // A cache that no longer parses (e.g. after an update) is simply dropped.
+  return parsed.success ? parsed.data : State.parse({});
+}
+
+export async function saveState(state: State): Promise<void> {
+  await writeAtomically(STATE, JSON.stringify(state, null, 2));
+}

package/server/view.ts

@@ -0,0 +1,37 @@
+import { type Attention, type AttentionView, type FeedId, type FeedStatus, type Item, type Section, SECTION_ORDER, SECTIONS, type TabId } from "../shared/attention";
+import type { AttentionConfig } from "../shared/config";
+import type { State } from "./store";
+
+export interface ViewMeta {
+  feeds: Record<FeedId, FeedStatus>;
+  scopes: string[];
+  config: AttentionConfig;
+}
+
+// A dismissed item stays hidden until someone else does something on it or its reason changes [ATT-08].
+export function isDismissed(item: Item, dismissed: State["dismissed"]): boolean {
+  const entry = dismissed[item.key];
+  return !!entry && entry.section === item.section && item.othersActivityAt <= entry.at;
+}
+
+export function buildView(attention: Attention | null, history: Item[], dismissed: State["dismissed"], meta: ViewMeta): AttentionView {
+  const items = [...(attention?.items ?? []), ...history];
+  const visible = items.filter((item) => !isDismissed(item, dismissed));
+  const sections = (tab: TabId): Section[] =>
+    SECTION_ORDER.filter((id) => SECTIONS[id].tab === tab)
+      .map((id) => ({ id, title: SECTIONS[id].title, items: visible.filter((item) => item.section === id) }))
+      .filter((section) => section.items.length > 0);
+  const doing = sections("doing");
+  return {
+    ...meta,
+    login: attention?.login ?? null,
+    count: doing.reduce((sum, section) => sum + section.items.length, 0),
+    doing,
+    waiting: sections("waiting"),
+    history: visible.filter((item) => SECTIONS[item.section].tab === "history"),
+    assigned: attention?.assigned ?? [],
+    unclaimed: attention?.unclaimed ?? [],
+    unclaimedFrom: attention?.unclaimedFrom ?? "config",
+    dismissedCount: items.length - visible.length,
+  };
+}

package/shared/attention.ts

@@ -0,0 +1,208 @@
+import type { AttentionConfig, MergeMethod } from "./config";
+
+// Tabs tell the story of my work: what I finished, what needs me, what waits on others, what's next.
+export type TabId = "history" | "doing" | "waiting" | "next";
+
+// Each tab's data comes from one feed, fetched from GitHub on its own schedule. History changes only when I finish something.
+export type FeedId = "live" | "history";
+export const TAB_FEED: Record<TabId, FeedId> = { history: "history", doing: "live", waiting: "live", next: "live" };
+
+// Within a tab, top to bottom; an item appears once, under its most urgent reason [ATT-02].
+export const SECTIONS = {
+  reply: { tab: "doing", title: "Waiting for your reply" },
+  review: { tab: "doing", title: "Review requested" },
+  ci: { tab: "doing", title: "CI failing" },
+  changes: { tab: "doing", title: "Changes requested" },
+  ready: { tab: "doing", title: "Ready to merge" },
+  upstream: { tab: "doing", title: "Needs upstream" },
+  too_long: { tab: "doing", title: "Waiting too long" },
+  drafts: { tab: "doing", title: "My drafts" },
+  // [WAI-01]
+  wait_review: { tab: "waiting", title: "Waiting for review" },
+  wait_reviewer: { tab: "waiting", title: "Waiting for the reviewer" },
+  wait_ci: { tab: "waiting", title: "CI running" },
+  wait_answer: { tab: "waiting", title: "Questions I asked" },
+  // [HIS-01, HIS-02]
+  done: { tab: "history", title: "Done" },
+  reviewed: { tab: "history", title: "Reviewed" },
+} as const satisfies Record<string, { tab: TabId; title: string }>;
+export type SectionId = keyof typeof SECTIONS;
+export const SECTION_ORDER = Object.keys(SECTIONS) as SectionId[];
+
+// The first is the card's main action; the item's sheet lists them all.
+export type ActionId =
+  | "reply"
+  | "acknowledge"
+  | "review"
+  | "fix"
+  | "rerun"
+  | "address"
+  | "update"
+  | "rebase"
+  | "refresh"
+  | "ready"
+  | "automerge"
+  | "merge"
+  | "close"
+  | "start";
+
+// A short state label on a row [ATT-05]; tone picks its color.
+export interface Chip {
+  text: string;
+  tone: "good" | "bad" | "warn" | "neutral";
+}
+
+// The person (or bot) I'm waiting on, or who is waiting on me.
+export interface Person {
+  login: string;
+  avatarUrl?: string;
+  bot: boolean;
+  since: string;
+  snippet?: string;
+  url?: string;
+  // Mentions only: every comment still waiting on me, for 👍 [MEN-02].
+  comments?: WaitingComment[];
+}
+
+export interface WaitingComment {
+  // The comment's node, or the issue or PR when its description mentions me.
+  id: string;
+  author: string;
+  body: string;
+  createdAt: string;
+  url?: string;
+}
+
+// What a session or GitHub action works on.
+export interface Target {
+  kind: "pr" | "issue";
+  repo: string;
+  number: number;
+  title: string;
+  url: string;
+  // Pull requests only.
+  id?: string;
+  headRefName?: string;
+  baseRefName?: string;
+  headRefOid?: string;
+  defaultBranch?: string;
+  mergeMethod?: MergeMethod;
+  // Every PR in the stack, bottom first.
+  stack?: { number: number; head: string; base: string }[];
+}
+
+export interface SubRow {
+  key: string;
+  number: number;
+  title: string;
+  url: string;
+  draft: boolean;
+  chips: Chip[];
+  // Behind its parent, conflicting or failing CI: shown even when the stack is collapsed.
+  attention: boolean;
+}
+
+export interface Item {
+  key: string;
+  section: SectionId;
+  kind: "pr" | "issue";
+  draft: boolean;
+  repo: string;
+  number: number;
+  title: string;
+  url: string;
+  chips: Chip[];
+  person?: Person;
+  actions: ActionId[];
+  // Linked PRs under an issue, or the PRs above the bottom of a stack.
+  children: SubRow[];
+  target: Target;
+  // Latest activity by someone else, for bringing back dismissed items [ATT-08].
+  othersActivityAt: string;
+  // History only: when it merged or closed.
+  closedAt?: string;
+}
+
+// An issue to pick up: assigned to me [NXT-06] or nobody [NXT-01].
+export interface NextUpIssue {
+  key: string;
+  repo: string;
+  number: number;
+  title: string;
+  url: string;
+  createdAt: string;
+  type?: string;
+  priority?: string;
+  effort?: string;
+  scope?: string;
+  defaultBranch?: string;
+}
+
+// More about an item, fetched when its sheet opens rather than in every refresh [GH-01].
+export interface ItemDetails {
+  // The PR actions apply to.
+  size?: { additions: number; deletions: number; files: number };
+  // The issues a PR closes, or the PRs that close an issue.
+  linked: { number: number; title: string; url: string; state: string }[];
+  // Only asked for when the item offers Rerun: each PR in the stack with failing checks.
+  failing: FailingChecks[];
+}
+
+export interface FailingChecks {
+  pr: number;
+  // Checks from GitHub Actions can be rerun; other status checks can't.
+  checks: { name: string; rerunnable: boolean }[];
+  runs: { id: number; attempt: number }[];
+}
+
+// Where Next up's unclaimed issues came from: the config, my Paseo projects' repos, or nowhere [NXT-08].
+export type UnclaimedSource = "config" | "projects" | "none";
+
+export interface Attention {
+  login: string;
+  items: Item[];
+  assigned: NextUpIssue[];
+  unclaimed: NextUpIssue[];
+  unclaimedFrom?: UnclaimedSource;
+}
+
+export interface Section {
+  id: SectionId;
+  title: string;
+  items: Item[];
+}
+
+// A Paseo session started from an item [ATT-07].
+export interface AgentSummary {
+  id: string;
+  status: string;
+  requiresAttention: boolean;
+  title: string | null;
+  workspaceId: string | null;
+}
+
+export interface FeedStatus {
+  fetchedAt: string | null;
+  refreshing: boolean;
+  error: string | null;
+}
+
+// What the client renders: dismissed items removed, grouped per tab.
+export interface AttentionView {
+  feeds: Record<FeedId, FeedStatus>;
+  login: string | null;
+  // Items in Doing; the sidebar shows it [ATT-09].
+  count: number;
+  doing: Section[];
+  waiting: Section[];
+  history: Item[];
+  assigned: NextUpIssue[];
+  unclaimed: NextUpIssue[];
+  unclaimedFrom: UnclaimedSource;
+  dismissedCount: number;
+  // Scope chips picked on Next up; none means all [NXT-03].
+  scopes: string[];
+  config: AttentionConfig;
+  // Fixture mode only: made-up sessions, since the preview daemon has no agents.
+  fixtureAgents?: Record<string, AgentSummary>;
+}