@agentprojectcontext/apx 1.77.3 → 1.79.0

package/src/interfaces/web/src/lib/api/skills.ts

@@ -102,13 +102,13 @@ export const Skills = {
       qs.set("scope", projectPath);
     }
     const q = qs.toString();
-    return http.get<SkillsList>(q ? `/skills?${q}` : "/skills");
+    return http.get<SkillsList>(q ? `/api/skills?${q}` : "/api/skills");
   },
 
   /** Full body + frontmatter of a skill, for the viewer. */
   detail: (slug: string, projectPath?: string) => {
     const qs = projectPath ? `?project_path=${encodeURIComponent(projectPath)}` : "";
-    return http.get<SkillDetail>(`/skills/${encodeURIComponent(slug)}/detail${qs}`);
+    return http.get<SkillDetail>(`/api/skills/${encodeURIComponent(slug)}/detail${qs}`);
   },
 
   /**
@@ -118,7 +118,7 @@ export const Skills = {
    */
   setEnabled: (body: { slug: string; enabled: boolean | null; scope?: string }) =>
     http.put<{ ok: boolean; slug: string; scope: string; enabled: boolean | null }>(
-      "/skills/enabled",
+      "/api/skills/enabled",
       body,
     ),
 
@@ -127,39 +127,39 @@ export const Skills = {
    * that project's .apc/skills/; otherwise in ~/.apx/skills/.
    */
   create: (body: { slug: string; description?: string; body?: string; project_path?: string }) =>
-    http.post<CreateResult>("/skills", body),
+    http.post<CreateResult>("/api/skills", body),
 
   /** Import a skill from an uploaded .zip (base64-encoded). */
   importZip: (body: { data: string; project_path?: string }) =>
-    http.post<CreateResult>("/skills/import/zip", body),
+    http.post<CreateResult>("/api/skills/import/zip", body),
 
   /** Import a skill by cloning a git repo. */
   importRepo: (body: { url: string; project_path?: string }) =>
-    http.post<CreateResult>("/skills/import/repo", body),
+    http.post<CreateResult>("/api/skills/import/repo", body),
 
   /** Delete a user skill (global or project-scoped). */
   remove: (slug: string, projectPath?: string) => {
     const qs = projectPath ? `?project_path=${encodeURIComponent(projectPath)}` : "";
-    return http.del<{ ok: boolean; slug: string }>(`/skills/${encodeURIComponent(slug)}${qs}`);
+    return http.del<{ ok: boolean; slug: string }>(`/api/skills/${encodeURIComponent(slug)}${qs}`);
   },
 
   /** Skill Inspector config + index status. */
-  inspector: () => http.get<InspectorState>("/skills/inspector"),
+  inspector: () => http.get<InspectorState>("/api/skills/inspector"),
 
   /** Patch inspector config (toggle / tune thresholds). */
   updateInspector: (patch: Partial<InspectorConfig>) =>
     http.put<{ ok: boolean; config: InspectorConfig; index: IndexStatus }>(
-      "/skills/inspector",
+      "/api/skills/inspector",
       patch,
     ),
 
   /** (Re)build the inspector vector index. */
   index: (body: { project_path?: string; force?: boolean } = {}) =>
-    http.post<IndexResult>("/skills/index", body),
+    http.post<IndexResult>("/api/skills/index", body),
 
   /** Dry-run the inspector for a prompt (forces enabled). */
   inspect: (prompt: string, projectPath?: string) =>
-    http.post<InspectResult>("/skills/inspect", {
+    http.post<InspectResult>("/api/skills/inspect", {
       prompt,
       project_path: projectPath,
     }),

package/src/interfaces/web/src/lib/api/super_agent.ts

@@ -14,7 +14,7 @@ export interface SuperAgentSendBody {
 export const SuperAgent = {
   send: (pid: string | number, body: SuperAgentSendBody) =>
     http.post<{ text: string; usage?: unknown; name?: string }>(
-      `/projects/${pid}/super-agent/chat`,
+      `/api/projects/${pid}/super-agent/chat`,
       body,
     ),
   stream: (
@@ -22,8 +22,8 @@ export const SuperAgent = {
     body: SuperAgentSendBody,
     onEvent: (ev: ChatStreamEvent) => void,
     signal?: AbortSignal,
-  ) => streamNdjson<ChatStreamEvent>(`/projects/${pid}/super-agent/chat/stream`, body, onEvent, signal),
+  ) => streamNdjson<ChatStreamEvent>(`/api/projects/${pid}/super-agent/chat/stream`, body, onEvent, signal),
 
   summarize: (body: { prompt: string; context_note?: string; model?: string }) =>
-    http.post<{ text: string; usage?: unknown; name?: string }>("/super-agent/summarize", body),
+    http.post<{ text: string; usage?: unknown; name?: string }>("/api/super-agent/summarize", body),
 };

package/src/interfaces/web/src/lib/api/tasks.ts

@@ -18,28 +18,28 @@ export interface TaskSummary {
 export const Tasks = {
   // Full sets (no pagination) — unwrapped to plain arrays for non-paged callers.
   list:   (pid: string, state: TaskEntry["state"] | "all" = "open") =>
-    http.get<unknown>(`/projects/${pid}/tasks?state=${state}`).then((b) => unwrapPage<TaskEntry>(b).items),
+    http.get<unknown>(`/api/projects/${pid}/tasks?state=${state}`).then((b) => unwrapPage<TaskEntry>(b).items),
   global: (state: TaskEntry["state"] | "all" = "open") =>
-    http.get<unknown>(`/tasks?state=${state}`).then((b) => unwrapPage<GlobalTaskEntry>(b).items),
+    http.get<unknown>(`/api/tasks?state=${state}`).then((b) => unwrapPage<GlobalTaskEntry>(b).items),
   // Server-paginated variants: one project (listPage) or all projects
   // (globalPage). Each returns the requested window plus the full total.
   listPage: (pid: string, { state, limit, offset }: { state: TaskEntry["state"] | "all"; limit: number; offset: number }) =>
-    http.get<unknown>(`/projects/${pid}/tasks?state=${state}&limit=${limit}&offset=${offset}`).then((b) => unwrapPage<TaskEntry>(b)),
+    http.get<unknown>(`/api/projects/${pid}/tasks?state=${state}&limit=${limit}&offset=${offset}`).then((b) => unwrapPage<TaskEntry>(b)),
   globalPage: ({ state, limit, offset, status }: { state: TaskEntry["state"] | "all"; limit: number; offset: number; status?: TaskStatus | "" }) =>
     http
       .get<unknown>(
-        `/tasks?state=${state}&limit=${limit}&offset=${offset}` + (status ? `&status=${status}` : ""),
+        `/api/tasks?state=${state}&limit=${limit}&offset=${offset}` + (status ? `&status=${status}` : ""),
       )
       .then((b) => unwrapPage<GlobalTaskEntry>(b)),
-  get:    (pid: string, id: string) => http.get<TaskEntry>(`/projects/${pid}/tasks/${id}`),
+  get:    (pid: string, id: string) => http.get<TaskEntry>(`/api/projects/${pid}/tasks/${id}`),
   add:    (pid: string, body: Partial<TaskEntry>) =>
-    http.post<TaskEntry>(`/projects/${pid}/tasks`, body),
+    http.post<TaskEntry>(`/api/projects/${pid}/tasks`, body),
   patch:  (pid: string, id: string, patch: Partial<TaskEntry>) =>
-    http.patch<TaskEntry>(`/projects/${pid}/tasks/${id}`, { patch }),
+    http.patch<TaskEntry>(`/api/projects/${pid}/tasks/${id}`, { patch }),
   status: (pid: string, id: string, status: TaskStatus) =>
-    http.post<TaskEntry>(`/projects/${pid}/tasks/${id}/status`, { status }),
-  done:   (pid: string, id: string) => http.post<TaskEntry>(`/projects/${pid}/tasks/${id}/done`),
-  drop:   (pid: string, id: string) => http.post<TaskEntry>(`/projects/${pid}/tasks/${id}/drop`),
-  reopen: (pid: string, id: string) => http.post<TaskEntry>(`/projects/${pid}/tasks/${id}/reopen`),
-  summary: (pid: string) => http.get<TaskSummary>(`/projects/${pid}/tasks-summary`),
+    http.post<TaskEntry>(`/api/projects/${pid}/tasks/${id}/status`, { status }),
+  done:   (pid: string, id: string) => http.post<TaskEntry>(`/api/projects/${pid}/tasks/${id}/done`),
+  drop:   (pid: string, id: string) => http.post<TaskEntry>(`/api/projects/${pid}/tasks/${id}/drop`),
+  reopen: (pid: string, id: string) => http.post<TaskEntry>(`/api/projects/${pid}/tasks/${id}/reopen`),
+  summary: (pid: string) => http.get<TaskSummary>(`/api/projects/${pid}/tasks-summary`),
 };

package/src/interfaces/web/src/lib/api/telegram.ts

@@ -21,37 +21,37 @@ export interface TelegramSendBody {
 
 export const Telegram = {
   channels: {
-    list:   () => http.get<TelegramChannelsResponse>("/telegram/channels"),
+    list:   () => http.get<TelegramChannelsResponse>("/api/telegram/channels"),
     upsert: (ch: TelegramChannel) =>
-      http.post<{ channel: TelegramChannel; created: boolean }>("/telegram/channels", ch),
+      http.post<{ channel: TelegramChannel; created: boolean }>("/api/telegram/channels", ch),
     patch:  (name: string, body: Partial<TelegramChannel>) =>
-      http.patch<{ ok: true; channel: TelegramChannel }>(`/telegram/channels/${name}`, body),
+      http.patch<{ ok: true; channel: TelegramChannel }>(`/api/telegram/channels/${name}`, body),
     remove: (name: string) =>
-      http.del<void>(`/telegram/channels/${encodeURIComponent(name)}`),
+      http.del<void>(`/api/telegram/channels/${encodeURIComponent(name)}`),
   },
   contacts: {
-    list:   () => http.get<TelegramContactsResponse>("/telegram/contacts"),
+    list:   () => http.get<TelegramContactsResponse>("/api/telegram/contacts"),
     patch:  (userId: number | string, body: Partial<TelegramContact>) =>
       http.patch<{ ok: true; contact: TelegramContact }>(
-        `/telegram/contacts/${encodeURIComponent(String(userId))}`,
+        `/api/telegram/contacts/${encodeURIComponent(String(userId))}`,
         body,
       ),
     remove: (userId: number | string) =>
-      http.del<void>(`/telegram/contacts/${encodeURIComponent(String(userId))}`),
+      http.del<void>(`/api/telegram/contacts/${encodeURIComponent(String(userId))}`),
   },
   roles: {
-    list:   () => http.get<{ roles: Record<string, TelegramRole> }>("/telegram/roles"),
+    list:   () => http.get<{ roles: Record<string, TelegramRole> }>("/api/telegram/roles"),
     set:    (name: string, tools: "*" | string[]) =>
       http.put<{ ok: true; name: string; role: TelegramRole }>(
-        `/telegram/roles/${encodeURIComponent(name)}`,
+        `/api/telegram/roles/${encodeURIComponent(name)}`,
         { tools },
       ),
     remove: (name: string) =>
-      http.del<void>(`/telegram/roles/${encodeURIComponent(name)}`),
+      http.del<void>(`/api/telegram/roles/${encodeURIComponent(name)}`),
   },
-  status: () => http.get<TelegramStatus>("/telegram/status"),
-  start:  () => http.post<{ ok: true; status: TelegramStatus }>("/telegram/start"),
-  stop:   () => http.post<{ ok: true; status: TelegramStatus }>("/telegram/stop"),
+  status: () => http.get<TelegramStatus>("/api/telegram/status"),
+  start:  () => http.post<{ ok: true; status: TelegramStatus }>("/api/telegram/start"),
+  stop:   () => http.post<{ ok: true; status: TelegramStatus }>("/api/telegram/stop"),
   send:   (body: TelegramSendBody) =>
-    http.post<{ ok: true; message_id: number }>("/telegram/send", body),
+    http.post<{ ok: true; message_id: number }>("/api/telegram/send", body),
 };

package/src/interfaces/web/src/lib/api/tools.ts

@@ -9,5 +9,5 @@ export interface ToolInfo {
 
 export const Tools = {
   // Registry of built-in tools the daemon exposes.
-  list: () => http.get<ToolInfo[]>("/tools"),
+  list: () => http.get<ToolInfo[]>("/api/tools"),
 };

package/src/interfaces/web/src/lib/api/vars.ts

@@ -20,19 +20,19 @@ export interface VarDetail {
 export const Vars = {
   list: (pid: string, opts: { reveal?: boolean } = {}) =>
     http.get<VarsList>(
-      `/projects/${pid}/vars${opts.reveal ? "?reveal=1" : ""}`,
+      `/api/projects/${pid}/vars${opts.reveal ? "?reveal=1" : ""}`,
     ),
   get: (pid: string, name: string, opts: { reveal?: boolean } = {}) =>
     http.get<VarDetail>(
-      `/projects/${pid}/vars/${encodeURIComponent(name)}${opts.reveal ? "?reveal=1" : ""}`,
+      `/api/projects/${pid}/vars/${encodeURIComponent(name)}${opts.reveal ? "?reveal=1" : ""}`,
     ),
   upsert: (pid: string, body: { name: string; value: string; scope?: VarScope }) =>
     http.post<{ ok: true; name: string; scope: VarScope }>(
-      `/projects/${pid}/vars`,
+      `/api/projects/${pid}/vars`,
       body,
     ),
   remove: (pid: string, name: string, scope: VarScope = "project") =>
     http.del<void>(
-      `/projects/${pid}/vars/${encodeURIComponent(name)}?scope=${scope}`,
+      `/api/projects/${pid}/vars/${encodeURIComponent(name)}?scope=${scope}`,
     ),
 };

package/src/interfaces/web/src/lib/api/voice.ts

@@ -220,7 +220,7 @@ export const TTS_PROVIDER_ORDER: TtsProviderId[] = ["piper", "elevenlabs", "open
  */
 export async function fetchTtsAudioUrl(audioPath: string): Promise<string> {
   const token = getToken();
-  const res = await fetch(`/voice/tts?path=${encodeURIComponent(audioPath)}`, {
+  const res = await fetch(`/api/voice/tts?path=${encodeURIComponent(audioPath)}`, {
     headers: token ? { authorization: `Bearer ${token}` } : {},
   });
   if (!res.ok) {
@@ -233,13 +233,13 @@ export async function fetchTtsAudioUrl(audioPath: string): Promise<string> {
 
 export const Voice = {
   /** List TTS engines + availability + the configured default provider. */
-  providers: () => http.get<TtsProvidersResponse>("/tts/providers"),
+  providers: () => http.get<TtsProvidersResponse>("/api/tts/providers"),
 
   /** Detected hardware + the recommended local STT backend (Metal/CUDA/CPU). */
-  sttHardware: () => http.get<SttHardwareResponse>("/transcribe/hardware"),
+  sttHardware: () => http.get<SttHardwareResponse>("/api/transcribe/hardware"),
 
   /** Model catalog + on-disk status for a local backend ("faster" | "mlx"). */
-  sttModels: (backend: string) => http.get<SttModelsResponse>(`/transcribe/models?backend=${backend}`),
+  sttModels: (backend: string) => http.get<SttModelsResponse>(`/api/transcribe/models?backend=${backend}`),
 
   /**
    * Synthesize speech. Returns the audio file path (server-side); the web
@@ -247,7 +247,7 @@ export const Voice = {
    * is irrelevant for the web (the daemon never plays for HTTP callers).
    */
   say: (body: { text: string; provider?: string; voice?: string; language?: string; format?: string; style?: string }) =>
-    http.post<TtsSayResult>("/tts/say", body),
+    http.post<TtsSayResult>("/api/tts/say", body),
 
   /**
    * One bidirectional voice turn (STT → agent → TTS). The web uses the
@@ -261,5 +261,5 @@ export const Voice = {
     provider?: string;
     voice?: string;
     language?: string;
-  }) => http.post<VoiceTurnResult>("/voice/turn", body),
+  }) => http.post<VoiceTurnResult>("/api/voice/turn", body),
 };

package/src/interfaces/web/src/lib/cron.ts

@@ -0,0 +1,196 @@
+/**
+ * Five-field cron ⇄ human, both directions.
+ *
+ * `30 8 * * 1-5` is not a thing anyone should have to read to answer "when
+ * does my morning message arrive". Two pure functions, one file, so the
+ * summary shown in a status line and the picker used in a form can never
+ * disagree about what an expression means.
+ *
+ * Deliberately NOT a general cron library. It covers what APX writes and what
+ * the picker produces — fixed time, day-of-week sets, day-of-month, and
+ * step values — and says plainly when it does not understand something rather
+ * than guessing. `describeCron` returning null is the signal for a surface to
+ * fall back to showing the raw expression.
+ */
+
+export interface CronParts {
+  minute: string;
+  hour: string;
+  dom: string;
+  month: string;
+  dow: string;
+}
+
+/** What a picker edits. */
+export interface CronSelection {
+  /** "HH:MM" in the machine's local time. */
+  time: string;
+  /** 0=Sunday … 6=Saturday. Empty = every day. */
+  days: number[];
+  /** Run every N hours instead of at a fixed time. 0 = off. */
+  everyHours: number;
+}
+
+export const DAY_KEYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"] as const;
+
+export function parseCron(expr: string): CronParts | null {
+  const f = String(expr || "").trim().split(/\s+/);
+  if (f.length !== 5) return null;
+  return { minute: f[0], hour: f[1], dom: f[2], month: f[3], dow: f[4] };
+}
+
+// Expand `1-5`, `1,3,5`, `*` and step values like `*/2` into concrete numbers.
+// (Kept as a line comment: a `*/` inside a block comment closes it.)
+function expand(field: string, min: number, max: number): number[] | null {
+  const out = new Set<number>();
+  for (const part of String(field).split(",")) {
+    const step = part.match(/^(.+)\/(\d+)$/);
+    const body = step ? step[1] : part;
+    const by = step ? Number(step[2]) : 1;
+    if (!Number.isFinite(by) || by < 1) return null;
+
+    let lo: number;
+    let hi: number;
+    if (body === "*") { lo = min; hi = max; }
+    else {
+      const range = body.match(/^(\d+)-(\d+)$/);
+      if (range) { lo = Number(range[1]); hi = Number(range[2]); }
+      else if (/^\d+$/.test(body)) { lo = Number(body); hi = lo; }
+      else return null;
+    }
+    if (lo < min || hi > max || lo > hi) return null;
+    for (let v = lo; v <= hi; v += by) out.add(v);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
+/** Day numbers a cron dow field selects. Cron accepts 7 for Sunday. */
+export function cronDays(dow: string): number[] | null {
+  if (dow === "*" || dow === "?") return [];
+  const nums = expand(dow.replace(/\b7\b/g, "0"), 0, 6);
+  return nums && nums.length ? nums : null;
+}
+
+/**
+ * A sentence. Returns null when the expression is beyond what this understands
+ * — the caller shows the raw cron rather than a confident wrong reading.
+ */
+export function describeCron(
+  expr: string,
+  t: (key: string, vars?: Record<string, string | number>) => string,
+): string | null {
+  const p = parseCron(expr);
+  if (!p) return null;
+  if (p.month !== "*") return null;      // "in March" is not a case APX writes
+  if (p.dom !== "*" && p.dow !== "*") return null; // both set is ambiguous in cron itself
+
+  // Every N hours: `0 */2 * * *`.
+  const stepHour = p.hour.match(/^\*\/(\d+)$/);
+  if (stepHour && /^\d+$/.test(p.minute)) {
+    const n = Number(stepHour[1]);
+    return n === 1
+      ? t("cron.every_hour", { minute: pad(Number(p.minute)) })
+      : t("cron.every_n_hours", { n, minute: pad(Number(p.minute)) });
+  }
+  // Every N minutes: `*/15 * * * *`.
+  const stepMin = p.minute.match(/^\*\/(\d+)$/);
+  if (stepMin && p.hour === "*") return t("cron.every_n_minutes", { n: Number(stepMin[1]) });
+  if (p.minute === "*" && p.hour === "*") return t("cron.every_minute");
+
+  const hours = expand(p.hour, 0, 23);
+  const minutes = expand(p.minute, 0, 59);
+  if (!hours || !minutes || minutes.length !== 1) return null;
+
+  const at = hours.length === 1
+    ? `${pad(hours[0])}:${pad(minutes[0])}`
+    : hours.map((h) => `${pad(h)}:${pad(minutes[0])}`).join(", ");
+
+  if (p.dom !== "*") {
+    const doms = expand(p.dom, 1, 31);
+    if (!doms || doms.length !== 1) return null;
+    return t("cron.monthly", { day: doms[0], at });
+  }
+
+  const days = cronDays(p.dow);
+  if (days === null) return null;
+  if (!days.length) return t("cron.daily", { at });
+
+  const weekdays = [1, 2, 3, 4, 5];
+  const isWeekdays = days.length === 5 && weekdays.every((d) => days.includes(d));
+  if (isWeekdays) return t("cron.weekdays", { at });
+  if (days.length === 2 && days.includes(0) && days.includes(6)) return t("cron.weekends", { at });
+
+  const names = days.map((d) => t(`cron.day_short.${DAY_KEYS[d]}`)).join(", ");
+  return t("cron.on_days", { days: names, at });
+}
+
+/** Cron → what a picker should show. */
+export function cronToSelection(expr: string): CronSelection {
+  const p = parseCron(expr);
+  const fallback: CronSelection = { time: "08:00", days: [], everyHours: 0 };
+  if (!p) return fallback;
+
+  const stepHour = p.hour.match(/^\*\/(\d+)$/);
+  if (stepHour) {
+    return {
+      time: `00:${pad(Number(/^\d+$/.test(p.minute) ? p.minute : 0))}`,
+      days: [],
+      everyHours: Number(stepHour[1]),
+    };
+  }
+  const hours = expand(p.hour, 0, 23);
+  const minutes = expand(p.minute, 0, 59);
+  const days = cronDays(p.dow);
+  return {
+    time: hours?.length && minutes?.length ? `${pad(hours[0])}:${pad(minutes[0])}` : fallback.time,
+    days: days ?? [],
+    everyHours: 0,
+  };
+}
+
+/** What a picker produces. Always a valid five-field expression. */
+export function selectionToCron(sel: CronSelection): string {
+  if (sel.everyHours > 0) {
+    const [, mm] = splitTime(sel.time);
+    return `${mm} */${clamp(sel.everyHours, 1, 23)} * * *`;
+  }
+  const [hh, mm] = splitTime(sel.time);
+  // Sorted, and 0 kept as 0 — cron accepts both 0 and 7 for Sunday, and
+  // writing one form consistently keeps round-tripping stable.
+  const dow = sel.days.length && sel.days.length < 7
+    ? [...sel.days].sort((a, b) => a - b).join(",")
+    : "*";
+  return `${mm} ${hh} * * ${dow}`;
+}
+
+/** Is this something the pickers can represent without losing information? */
+export function isPickerFriendly(expr: string): boolean {
+  const p = parseCron(expr);
+  if (!p) return false;
+  if (p.month !== "*" || p.dom !== "*") return false;
+  return selectionToCron(cronToSelection(expr)) === normalizeCron(expr);
+}
+
+/** `30 08 * * 1-5` → `30 8 * * 1,2,3,4,5`, so comparisons are meaningful. */
+export function normalizeCron(expr: string): string {
+  const p = parseCron(expr);
+  if (!p) return String(expr || "").trim();
+  const days = cronDays(p.dow);
+  const dow = days && days.length && days.length < 7 ? days.join(",") : "*";
+  const one = (f: string) => (/^\d+$/.test(f) ? String(Number(f)) : f);
+  return `${one(p.minute)} ${one(p.hour)} ${p.dom} ${p.month} ${dow}`;
+}
+
+function splitTime(time: string): [string, string] {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(String(time || "").trim());
+  if (!m) return ["8", "0"];
+  return [String(clamp(Number(m[1]), 0, 23)), String(clamp(Number(m[2]), 0, 59))];
+}
+
+function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+function clamp(n: number, lo: number, hi: number): number {
+  return Math.min(hi, Math.max(lo, Number.isFinite(n) ? n : lo));
+}

package/src/interfaces/web/src/lib/when.ts

@@ -0,0 +1,32 @@
+/**
+ * "in 8 hours" / "2 minutes ago".
+ *
+ * A status row showing two absolute timestamps makes the reader do the
+ * arithmetic that the row exists to save them. The absolute value stays
+ * available as a tooltip for when the exact minute is what matters.
+ */
+type T = (key: string, vars?: Record<string, string | number>) => string;
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+export function relativeWhen(iso: string, t: T, now: number = Date.now()): string {
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms)) return "—";
+  const diff = ms - now;
+  const ahead = diff >= 0;
+  const abs = Math.abs(diff);
+
+  // Under a minute reads as "now" in both directions: "in 34 seconds" is
+  // precision nobody acts on.
+  if (abs < MINUTE) return t("when.now");
+
+  const [n, unit] =
+    abs < HOUR ? [Math.round(abs / MINUTE), "minutes"] :
+    abs < DAY ? [Math.round(abs / HOUR), "hours"] :
+    [Math.round(abs / DAY), "days"];
+
+  const amount = t(`when.${unit}`, { n });
+  return ahead ? t("when.in", { amount }) : t("when.ago", { amount });
+}