dayhand 0.0.0-stage → 0.14.0

package/backend/convex/lib/brief.ts

@@ -0,0 +1,132 @@
+// The agent brief (agent_brief, dayhand prime): what an agent needs at the start
+// of a session, from its own point of view. It is list_today with more fields:
+// the claims in force and the caller's own, the owner's pause and the caller's
+// tool policies, approval requests waiting and the caller's recent decisions,
+// the first tasks ready to work on, and next steps written out as sentences.
+import type { ObjectType } from "convex/values";
+import type { Doc } from "../_generated/dataModel";
+import type { QueryCtx } from "../_generated/server";
+import { getAgentControls } from "./agentControls";
+import { isReady, sameHolder } from "./agentWork";
+import { MAX_APPROVAL_MINUTES, statusOf } from "./approvals";
+import type { args } from "./args";
+import { loadSettings, type Identity } from "./core";
+import { localDateTime } from "./dates";
+import { listToday } from "./views";
+
+type Args = ObjectType<(typeof args)["agentBrief"]>;
+
+/** Items listed per section; `count` counts them all. */
+export const BRIEF_LIST = 10;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const APPROVAL_WINDOW_MS = MAX_APPROVAL_MINUTES * 60_000 + DAY_MS;
+
+const brief = (t: Doc<"tasks">) => ({ id: t._id, ref: t.ref ?? null, title: t.title, status: t.status, dueDate: t.dueDate ?? null, dueTime: t.dueTime ?? null });
+const label = (t: Doc<"tasks">) => `#${t.ref ?? t._id} ${t.title}`;
+const section = <T>(items: T[]) => ({ count: items.length, items: items.slice(0, BRIEF_LIST) });
+
+const byDue = (a: Doc<"tasks">, b: Doc<"tasks">) =>
+  (a.dueDate ?? "9999").localeCompare(b.dueDate ?? "9999") || (a.dueTime ?? "99").localeCompare(b.dueTime ?? "99") || (a.ref ?? 0) - (b.ref ?? 0);
+
+function claimView(t: Doc<"tasks">, identity: Identity) {
+  return { ...brief(t), claimedBy: t.claimedBy!.name, claimExpiresAt: t.claimExpiresAt ?? null, mine: sameHolder(t.claimedBy, identity) };
+}
+
+function approvalItem(a: Doc<"approvals">, tasks: Map<string, Doc<"tasks">>, identity: Identity) {
+  const task = a.taskId ? tasks.get(a.taskId) : undefined;
+  const chosen = a.options.find((o) => o.id === a.optionId);
+  return {
+    id: a._id,
+    action: a.title,
+    taskId: a.taskId ?? null,
+    ref: task?.ref ?? null,
+    expiresAt: a.expiresAt,
+    requestedBy: a.requestedBy.name,
+    mine: sameHolder(a.requestedBy, identity),
+    decision: a.decidedAt === undefined ? null : { optionId: a.optionId!, label: chosen?.label ?? a.optionId!, note: a.note ?? null, decidedAt: a.decidedAt },
+  };
+}
+
+type Facts = {
+  paused: boolean;
+  reason: string | null;
+  mine: Doc<"tasks">[];
+  expiredMine: Doc<"tasks">[];
+  decided: Doc<"approvals">[];
+  waiting: Doc<"approvals">[];
+  overdue: number;
+  ready: Doc<"tasks">[];
+  timezone: string;
+};
+
+/** The next steps, most pressing first, as sentences that name the tools and resources to use. */
+function nextSteps(f: Facts): string[] {
+  const at = (ms: number) => localDateTime(ms, f.timezone);
+  if (f.paused) {
+    return [`The owner paused all agents${f.reason ? ` (${f.reason})` : ""}: read, but change nothing until they resume you; do not retry in a loop.`];
+  }
+  const steps = [
+    ...f.decided.map((a) => `The owner decided "${a.title}": ${a.options.find((o) => o.id === a.optionId)?.label ?? a.optionId}${a.note ? ` (${a.note})` : ""}. Act on that choice and nothing else.`),
+    ...f.mine.map((t) => `You hold ${label(t)} until ${at(t.claimExpiresAt!)}: renew_claim while you work, then complete_task with proof, or release_task with a checkpoint note (dayhand://workflow/execution).`),
+    ...f.expiredMine.map((t) => `Your claim of ${label(t)} ran out at ${at(t.claimExpiresAt!)}: renew_claim to go on (nobody took it over) or release_task.`),
+    ...f.waiting.map((a) => `Waiting for the owner on "${a.title}" until ${at(a.expiresAt)}: check get_approval before that step, and do not take it without a decision.`),
+  ];
+  if (f.overdue > 0) steps.push(`${f.overdue} task(s) are overdue: go through them with the owner (the prompt triage_overdue) before moving any.`);
+  if (f.mine.length === 0 && f.ready[0]) steps.push(`Ready to work on: ${label(f.ready[0])}. claim_task it first; write acceptance criteria if it has none (dayhand://workflow/intake).`);
+  if (f.mine.length === 0 && f.ready.length === 0) steps.push("Nothing is ready to work on: ask the owner, or propose work with add_task and proposal: true (dayhand://workflow/intake).");
+  return steps;
+}
+
+export async function agentBrief(ctx: QueryCtx, identity: Identity, input: Args) {
+  const at = input.at ?? Date.now();
+  const today = await listToday(ctx, identity, { at });
+  const { timezone } = await loadSettings(ctx, identity.userId);
+  const controls = await getAgentControls(ctx, identity);
+  const all = await ctx.db
+    .query("tasks")
+    .withIndex("by_user", (q) => q.eq("userId", identity.userId))
+    .collect();
+  const byId = new Map(all.map((t) => [t._id as string, t]));
+  const open = all.filter((t) => t.deletedAt === undefined && t.archivedAt === undefined && t.proposedAt === undefined && t.status !== "done");
+  const live = (t: Doc<"tasks">) => t.claimedBy !== undefined && (t.claimExpiresAt ?? 0) > at;
+  const active = open.filter(live).sort((a, b) => a.claimExpiresAt! - b.claimExpiresAt!);
+  const expired = open.filter((t) => t.claimedBy !== undefined && !live(t)).sort((a, b) => a.claimExpiresAt! - b.claimExpiresAt!);
+  const ready = open.filter((t) => isReady(t, byId) && !(live(t) && !sameHolder(t.claimedBy, identity))).sort(byDue);
+
+  const approvals = await ctx.db
+    .query("approvals")
+    .withIndex("by_user", (q) => q.eq("userId", identity.userId).gte("createdAt", at - APPROVAL_WINDOW_MS))
+    .collect();
+  const pending = approvals.filter((a) => statusOf(a, at) === "pending").sort((a, b) => a.expiresAt - b.expiresAt);
+  const decided = approvals.filter((a) => a.decidedAt !== undefined && a.decidedAt > at - DAY_MS && sameHolder(a.requestedBy, identity)).sort((a, b) => b.decidedAt! - a.decidedAt!);
+  const mine = active.filter((t) => sameHolder(t.claimedBy, identity));
+
+  return {
+    ...today,
+    at,
+    caller: { type: identity.actor, name: identity.actorName ?? null },
+    agentsPaused: controls.paused,
+    pausedReason: controls.reason,
+    policies: controls.policies.filter((p) => p.keyId === identity.keyId).map(({ tool, rule }) => ({ tool, rule })),
+    claims: {
+      active: section(active.map((t) => claimView(t, identity))),
+      expired: section(expired.map((t) => claimView(t, identity))),
+    },
+    approvals: {
+      pending: section(pending.map((a) => approvalItem(a, byId, identity))),
+      decided: section(decided.map((a) => approvalItem(a, byId, identity))),
+    },
+    ready: section(ready.map(brief)),
+    nextSteps: nextSteps({
+      paused: controls.paused,
+      reason: controls.reason,
+      mine,
+      expiredMine: expired.filter((t) => sameHolder(t.claimedBy, identity)),
+      decided,
+      waiting: pending.filter((a) => sameHolder(a.requestedBy, identity)),
+      overdue: today.overdue.length,
+      ready,
+      timezone,
+    }),
+  };
+}

package/backend/convex/lib/cimd.ts

@@ -0,0 +1,57 @@
+// Fetching a Client ID Metadata Document (draft-ietf-oauth-client-id-metadata-document).
+// Only URLs on the allowed origins are fetched (oauthConfig.cimdOrigins), so the
+// server never requests an address a stranger chose; redirects are refused and
+// the answer is cut off by size and time.
+import { cimdOrigins } from "./oauthConfig";
+import { checkMetadataDocument, cimdUrlProblem, type ClientCheck } from "./oauthRules";
+
+const MAX_DOCUMENT_BYTES = 16 * 1024;
+const FETCH_TIMEOUT_MS = 5_000;
+
+async function readLimited(response: Response): Promise<string | null> {
+  const reader = response.body?.getReader();
+  if (!reader) return null;
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > MAX_DOCUMENT_BYTES) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(value);
+  }
+  const all = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    all.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(all);
+}
+
+/** The client behind a URL client_id, or why it cannot be used. Never throws. */
+export async function fetchClientMetadata(clientId: string): Promise<ClientCheck> {
+  const problem = cimdUrlProblem(clientId, cimdOrigins());
+  if (problem) return { ok: false, error: problem };
+  let response: Response;
+  try {
+    response = await fetch(clientId, {
+      headers: { Accept: "application/json" },
+      redirect: "error",
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+  } catch {
+    return { ok: false, error: "Could not fetch the client metadata" };
+  }
+  if (response.status !== 200) return { ok: false, error: `Client metadata answered HTTP ${response.status}` };
+  const text = await readLimited(response).catch(() => null);
+  if (text === null) return { ok: false, error: "Client metadata is too large or unreadable" };
+  try {
+    return checkMetadataDocument(clientId, JSON.parse(text));
+  } catch {
+    return { ok: false, error: "Client metadata is not JSON" };
+  }
+}

package/backend/convex/lib/core.ts

@@ -0,0 +1,380 @@
+// Shared building blocks of the domain layer: identity, errors, history,
+// idempotency, settings and the public shape of a task.
+import { ConvexError } from "convex/values";
+import type { Doc, Id } from "../_generated/dataModel";
+import type { MutationCtx, QueryCtx } from "../_generated/server";
+import { isValidDate, isValidTime, localDate, resolveDate } from "./dates";
+import { validateRepeat } from "./repeat";
+import { RRuleError, parseRRule, toRRule } from "./rrule";
+import { queueTaskEvents } from "./webhookEvents";
+import type { Actor, ChecklistInput, ChecklistItem, Link, Reminder, RepeatInput, RepeatRule } from "./validators";
+
+/**
+ * Who is acting. Thin layers (app, MCP) establish it; the domain trusts it.
+ * Changes made with an API key also carry the key's id and name; changes made
+ * through an OAuth connection carry the connection's id and the client's name.
+ */
+export type Identity = {
+  userId: string;
+  actor: Actor;
+  keyId?: Id<"apiKeys">;
+  connectionId?: Id<"oauthGrants">;
+  actorName?: string;
+};
+
+/** The identity part of an internal function's arguments. */
+export function identityOf({ userId, actor, keyId, connectionId, actorName }: Identity): Identity {
+  return { userId, actor, keyId, connectionId, actorName };
+}
+
+/** How history shows who made a change: "app", "cli", "agent" or "agent: <key or client name>". */
+export function actorLabel(event: { actor: Actor; actorName?: string }): string {
+  return event.actor === "agent" && event.actorName ? `agent: ${event.actorName}` : event.actor;
+}
+
+// conflict (since 0.10.0): another agent holds the task's claim (claim_task).
+// Since 0.11.0 (docs/agent-work.md): agents_paused, the owner paused every agent;
+// forbidden, only the owner may do this or the owner's policy denies the tool;
+// approval_required, the owner's policy asks first (approvalId says which request).
+export type ErrorCode =
+  | "invalid_argument"
+  | "not_found"
+  | "unauthenticated"
+  | "precondition_failed"
+  | "conflict"
+  | "agents_paused"
+  | "forbidden"
+  | "approval_required";
+
+export function fail(code: ErrorCode, message: string, extra: { approvalId?: string } = {}): never {
+  throw new ConvexError({ code, message, ...extra });
+}
+
+/** Refuses an operation only the owner may run (the app, or a cli key at the owner's terminal). */
+export function ownerOnly(identity: Identity, what: string) {
+  if (identity.actor === "agent") fail("forbidden", `Only the owner can ${what} (in the app or with a cli key)`);
+}
+
+export const DEFAULT_SETTINGS = {
+  timezone: "Europe/London",
+  summaryTime: "05:00",
+  defaultReminderMinutes: [0],
+};
+
+export type Settings = typeof DEFAULT_SETTINGS;
+
+export async function loadSettings(ctx: QueryCtx, userId: string): Promise<Settings> {
+  const row = await ctx.db
+    .query("settings")
+    .withIndex("by_user", (q) => q.eq("userId", userId))
+    .unique();
+  if (!row) return { ...DEFAULT_SETTINGS };
+  return {
+    timezone: row.timezone,
+    summaryTime: row.summaryTime,
+    defaultReminderMinutes: row.defaultReminderMinutes,
+  };
+}
+
+export async function todayFor(ctx: QueryCtx, userId: string, at: number): Promise<string> {
+  const { timezone } = await loadSettings(ctx, userId);
+  return localDate(at, timezone);
+}
+
+/**
+ * A task as returned to clients: stable `id` and `ref`, no internal fields.
+ * A repeating task also carries its rule as an RFC 5545 RRULE (`rrule`).
+ */
+export function toTask(doc: Doc<"tasks">) {
+  const { _id, _creationTime, userId, ...fields } = doc;
+  return fields.repeat ? { id: _id, ...fields, rrule: toRRule(fields.repeat, fields.dueDate) } : { id: _id, ...fields };
+}
+export type TaskView = ReturnType<typeof toTask>;
+
+/**
+ * The version of a stored task as an HTTP entity tag (RFC 9110): it changes
+ * with every change to the task. Derived fields such as `overdue` are not part of it.
+ */
+export const versionTag = (task: { updatedAt: number }) => `"${task.updatedAt}"`;
+
+const TASK_REF = /^#(\d{1,15})$/;
+
+/** Loads one of the user's tasks by its id or by its number written as "#42". */
+export async function loadTask(ctx: QueryCtx, userId: string, taskId: string) {
+  const ref = TASK_REF.exec(taskId);
+  if (ref) {
+    const task = await ctx.db
+      .query("tasks")
+      .withIndex("by_user_ref", (q) => q.eq("userId", userId).eq("ref", Number(ref[1])))
+      .first();
+    if (!task) fail("not_found", `Task #${Number(ref[1])} not found`);
+    return task;
+  }
+  const id = ctx.db.normalizeId("tasks", taskId);
+  if (!id) fail("invalid_argument", `Invalid arguments: taskId must be a task id or "#<number>", got "${taskId}"`);
+  const task = await ctx.db.get(id);
+  if (!task || task.userId !== userId) fail("not_found", `Task ${taskId} not found`);
+  return task;
+}
+
+/** Gives the user's next task number. Numbers start at 1 and are never given twice. */
+export async function nextTaskRef(ctx: MutationCtx, userId: string): Promise<number> {
+  const counter = await ctx.db
+    .query("taskCounters")
+    .withIndex("by_user", (q) => q.eq("userId", userId))
+    .unique();
+  const ref = (counter?.lastRef ?? 0) + 1;
+  if (counter) await ctx.db.patch(counter._id, { lastRef: ref });
+  else await ctx.db.insert("taskCounters", { userId, lastRef: ref });
+  return ref;
+}
+
+/**
+ * The next position in the user's activity log (taskEvents.seq). It starts
+ * from the change's time in microseconds and grows by one past the last
+ * position, so it follows the order changes commit even when two changes
+ * share a millisecond: every task change reads and writes the counter, and
+ * Convex runs such mutations one after the other.
+ */
+async function nextEventSeq(ctx: MutationCtx, userId: string, at: number): Promise<number> {
+  const counter = await ctx.db
+    .query("eventCounters")
+    .withIndex("by_user", (q) => q.eq("userId", userId))
+    .unique();
+  const seq = Math.max((counter?.lastSeq ?? 0) + 1, at * 1000);
+  if (counter) await ctx.db.patch(counter._id, { lastSeq: seq });
+  else await ctx.db.insert("eventCounters", { userId, lastSeq: seq });
+  return seq;
+}
+
+export async function recordEvent(
+  ctx: MutationCtx,
+  identity: Identity,
+  event: {
+    taskId?: Id<"tasks">;
+    action: string;
+    before?: Record<string, unknown>;
+    after?: Record<string, unknown>;
+    clientId?: string;
+  },
+) {
+  const at = Date.now();
+  const eventId = await ctx.db.insert("taskEvents", {
+    userId: identity.userId,
+    actor: identity.actor,
+    keyId: identity.keyId,
+    connectionId: identity.connectionId,
+    actorName: identity.actorName,
+    at,
+    // Only changes of a task enter the activity log (list_events).
+    seq: event.taskId ? await nextEventSeq(ctx, identity.userId, at) : undefined,
+    ...event,
+  });
+  // A change of a task is also an event for the user's webhooks (lib/webhookEvents.ts).
+  if (event.taskId) {
+    const { taskId, action, before, after } = event;
+    const { userId, actor, actorName } = identity;
+    await queueTaskEvents(ctx, { userId, eventId, taskId, action, at, actor, actorName, before, after }, toTask);
+  }
+}
+
+/** Changed fields of `patch` relative to `doc`, as before/after maps. */
+export function diff<T extends Record<string, unknown>>(doc: T, patch: Partial<T>) {
+  const before: Record<string, unknown> = {};
+  const after: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(patch)) {
+    if (key === "updatedAt") continue;
+    if (JSON.stringify(doc[key]) !== JSON.stringify(value)) {
+      before[key] = doc[key] ?? null;
+      after[key] = value ?? null;
+    }
+  }
+  return { before, after, changed: Object.keys(after).length > 0 };
+}
+
+/** Applies a patch to a task and records it in history when anything changed. */
+export async function patchTask(
+  ctx: MutationCtx,
+  identity: Identity,
+  task: Doc<"tasks">,
+  action: string,
+  patch: Partial<Doc<"tasks">>,
+  clientId?: string,
+) {
+  const { before, after, changed } = diff(task, patch);
+  if (!changed) return task;
+  await ctx.db.patch(task._id, { ...patch, updatedAt: Date.now() });
+  await recordEvent(ctx, identity, { taskId: task._id, action, before, after, clientId });
+  return (await ctx.db.get(task._id))!;
+}
+
+/** The event of an operation already applied with this clientId, if any. */
+export async function appliedOperation(ctx: QueryCtx, userId: string, clientId?: string) {
+  if (clientId === undefined) return null;
+  return ctx.db
+    .query("taskEvents")
+    .withIndex("by_user_clientId", (q) => q.eq("userId", userId).eq("clientId", clientId))
+    .first();
+}
+
+/** Current state of the task touched by an already applied operation, or null. */
+export async function replay(ctx: MutationCtx, userId: string, clientId?: string) {
+  const event = await appliedOperation(ctx, userId, checkClientId(clientId));
+  if (!event) return null;
+  const task = event.taskId ? await ctx.db.get(event.taskId) : null;
+  if (!task) fail("not_found", "Task of this operation no longer exists");
+  return task;
+}
+
+// ---- Input checks shared by all operations ----
+
+const LIMITS = {
+  title: 500,
+  note: 20_000,
+  resumeNote: 2_000,
+  label: 50,
+  labels: 20,
+  links: 20,
+  url: 2_048,
+  clientId: 128,
+  checklist: 100,
+  checklistId: 64,
+  reminders: 5,
+  reminderMinutes: 7 * 24 * 60,
+  reminderDays: 30,
+};
+
+export function checkTitle(title: string): string {
+  const trimmed = title.trim();
+  if (!trimmed) fail("invalid_argument", "title must not be empty");
+  if (trimmed.length > LIMITS.title) fail("invalid_argument", `title is longer than ${LIMITS.title} characters`);
+  return trimmed;
+}
+
+export function checkText(field: "note" | "resumeNote", value: string): string | undefined {
+  if (value.length > LIMITS[field]) fail("invalid_argument", `${field} is longer than ${LIMITS[field]} characters`);
+  return value.trim() === "" ? undefined : value;
+}
+
+export function checkDueDate(value: string, today: string): string {
+  const resolved = resolveDate(value, today);
+  if (!resolved) fail("invalid_argument", `dueDate must be YYYY-MM-DD, "today" or "tomorrow", got "${value}"`);
+  return resolved;
+}
+
+export function checkDueTime(value: string): string {
+  if (!isValidTime(value)) fail("invalid_argument", `dueTime must be HH:MM (24h), got "${value}"`);
+  return value;
+}
+
+export function checkLabels(labels: string[]): string[] {
+  const cleaned = [...new Set(labels.map((l) => l.trim()).filter((l) => l !== ""))];
+  if (cleaned.length > LIMITS.labels) fail("invalid_argument", `at most ${LIMITS.labels} labels`);
+  if (cleaned.some((l) => l.length > LIMITS.label)) fail("invalid_argument", `labels are at most ${LIMITS.label} characters`);
+  return cleaned;
+}
+
+export function checkLinks(links: Link[]): Link[] {
+  if (links.length > LIMITS.links) fail("invalid_argument", `at most ${LIMITS.links} links`);
+  return links.map((link) => {
+    let parsed: URL;
+    try {
+      parsed = new URL(link.url);
+    } catch {
+      fail("invalid_argument", `invalid link URL "${link.url}"`);
+    }
+    if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") || link.url.length > LIMITS.url) {
+      fail("invalid_argument", `links must be http(s) URLs up to ${LIMITS.url} characters`);
+    }
+    const title = link.title?.trim();
+    return title ? { url: link.url, title } : { url: link.url };
+  });
+}
+
+/** A rule object, or an RFC 5545 RRULE string read in the user's time zone. */
+export function checkRepeat(input: RepeatInput, timezone: string): RepeatRule {
+  if (typeof input === "string") {
+    try {
+      return parseRRule(input, timezone);
+    } catch (error) {
+      if (error instanceof RRuleError) fail("invalid_argument", `repeat: ${error.message}`);
+      throw error;
+    }
+  }
+  const error = validateRepeat(input);
+  if (error) fail("invalid_argument", error);
+  return input;
+}
+
+/**
+ * The checklist as stored: trimmed titles in the given order, `done` false
+ * unless set, and an id for every item. New items get the next free `c<n>`.
+ * An empty list is no checklist.
+ */
+export function checkChecklist(items: ChecklistInput[]): ChecklistItem[] | undefined {
+  if (items.length > LIMITS.checklist) fail("invalid_argument", `at most ${LIMITS.checklist} checklist items`);
+  const given = items.map((item) => item.id).filter((id): id is string => id !== undefined);
+  if (given.some((id) => id.trim() === "" || id.length > LIMITS.checklistId)) {
+    fail("invalid_argument", `checklist item ids must be 1 to ${LIMITS.checklistId} characters`);
+  }
+  if (new Set(given).size !== given.length) fail("invalid_argument", "checklist item ids must be distinct");
+  const used = new Set(given);
+  let next = 1;
+  const freeId = () => {
+    while (used.has(`c${next}`)) next++;
+    used.add(`c${next}`);
+    return `c${next}`;
+  };
+  const checked = items.map((item) => {
+    const title = item.title.trim();
+    if (!title) fail("invalid_argument", "checklist items need a title");
+    if (title.length > LIMITS.title) fail("invalid_argument", `checklist items are at most ${LIMITS.title} characters`);
+    return { id: item.id ?? "", title, done: item.done ?? false };
+  });
+  const result = checked.map((item) => (item.id ? item : { ...item, id: freeId() }));
+  return result.length > 0 ? result : undefined;
+}
+
+/** Reminders as stored: checked, without duplicates, `daysBefore` only when not 0. Empty = none. */
+export function checkReminders(reminders: Reminder[]): Reminder[] {
+  if (reminders.length > LIMITS.reminders) fail("invalid_argument", `at most ${LIMITS.reminders} reminders per task`);
+  const seen = new Set<string>();
+  const result: Reminder[] = [];
+  for (const reminder of reminders) {
+    let clean: Reminder;
+    if ("minutesBefore" in reminder) {
+      const m = reminder.minutesBefore;
+      if (!Number.isInteger(m) || m < 0 || m > LIMITS.reminderMinutes) {
+        fail("invalid_argument", `reminders: minutesBefore must be whole minutes from 0 to ${LIMITS.reminderMinutes}`);
+      }
+      clean = { minutesBefore: m };
+    } else {
+      if (!isValidTime(reminder.time)) fail("invalid_argument", `reminders: time must be HH:MM (24h), got "${reminder.time}"`);
+      const days = reminder.daysBefore ?? 0;
+      if (!Number.isInteger(days) || days < 0 || days > LIMITS.reminderDays) {
+        fail("invalid_argument", `reminders: daysBefore must be a whole number from 0 to ${LIMITS.reminderDays}`);
+      }
+      clean = days === 0 ? { time: reminder.time } : { time: reminder.time, daysBefore: days };
+    }
+    const key = JSON.stringify(clean);
+    if (!seen.has(key)) result.push(clean);
+    seen.add(key);
+  }
+  return result;
+}
+
+export function checkClientId(clientId?: string): string | undefined {
+  if (clientId !== undefined && (clientId === "" || clientId.length > LIMITS.clientId)) {
+    fail("invalid_argument", `clientId must be 1 to ${LIMITS.clientId} characters`);
+  }
+  return clientId;
+}
+
+export function checkSchedule(dueDate: string | undefined, dueTime: string | undefined) {
+  if (dueTime !== undefined && dueDate === undefined) {
+    fail("invalid_argument", "dueTime needs a dueDate");
+  }
+  if (dueDate !== undefined && !isValidDate(dueDate)) {
+    fail("invalid_argument", `invalid dueDate "${dueDate}"`);
+  }
+}

package/backend/convex/lib/dates.ts

@@ -0,0 +1,114 @@
+// Calendar dates are plain YYYY-MM-DD strings in the user's time zone.
+// Everything that decides "today" or "overdue" lives in this file.
+
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const TIME_RE = /^([01]\d|2[0-3]):([0-5]\d)$/;
+
+export function isValidDate(value: string): boolean {
+  const match = DATE_RE.exec(value);
+  if (!match) return false;
+  const [, y, m, d] = match.map(Number);
+  const date = new Date(Date.UTC(y, m - 1, d));
+  return date.getUTCFullYear() === y && date.getUTCMonth() === m - 1 && date.getUTCDate() === d;
+}
+
+export function isValidTime(value: string): boolean {
+  return TIME_RE.test(value);
+}
+
+export function isValidTimezone(timezone: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-GB", { timeZone: timezone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The calendar date at instant `ms` in `timezone`. */
+export function localDate(ms: number, timezone: string): string {
+  const parts = new Intl.DateTimeFormat("en-GB", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(ms));
+  const get = (type: string) => parts.find((p) => p.type === type)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")}`;
+}
+
+/** "YYYY-MM-DD HH:MM" at instant `ms` in `timezone`. */
+export function localDateTime(ms: number, timezone: string): string {
+  const parts = new Intl.DateTimeFormat("en-GB", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+  }).formatToParts(new Date(ms));
+  const get = (type: string) => parts.find((p) => p.type === type)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")} ${get("hour")}:${get("minute")}`;
+}
+
+function toUtcDate(date: string): Date {
+  const [y, m, d] = date.split("-").map(Number);
+  return new Date(Date.UTC(y, m - 1, d));
+}
+
+function fromUtcDate(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+export function addDays(date: string, days: number): string {
+  const result = toUtcDate(date);
+  result.setUTCDate(result.getUTCDate() + days);
+  return fromUtcDate(result);
+}
+
+/** Adds months keeping `anchorDay` where the month allows it (Jan 31 -> Feb 28 -> Mar 31). */
+export function addMonths(date: string, months: number, anchorDay: number): string {
+  const start = toUtcDate(date);
+  const firstOfTarget = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth() + months, 1));
+  const lastDay = new Date(
+    Date.UTC(firstOfTarget.getUTCFullYear(), firstOfTarget.getUTCMonth() + 1, 0),
+  ).getUTCDate();
+  firstOfTarget.setUTCDate(Math.min(anchorDay, lastDay));
+  return fromUtcDate(firstOfTarget);
+}
+
+/** ISO weekday: 1 = Monday ... 7 = Sunday. */
+export function weekday(date: string): number {
+  const day = toUtcDate(date).getUTCDay();
+  return day === 0 ? 7 : day;
+}
+
+export function dayOfMonth(date: string): number {
+  return toUtcDate(date).getUTCDate();
+}
+
+/**
+ * Overdue = not done, still active, and due before today in the user's zone.
+ * The single definition used by every view.
+ */
+export function isOverdue(
+  task: { status: string; dueDate?: string; archivedAt?: number; deletedAt?: number },
+  today: string,
+): boolean {
+  return (
+    task.status !== "done" &&
+    task.archivedAt === undefined &&
+    task.deletedAt === undefined &&
+    task.dueDate !== undefined &&
+    task.dueDate < today
+  );
+}
+
+/** Accepts YYYY-MM-DD or the words "today" / "tomorrow". Returns null when invalid. */
+export function resolveDate(input: string, today: string): string | null {
+  const value = input.trim().toLowerCase();
+  if (value === "today") return today;
+  if (value === "tomorrow") return addDays(today, 1);
+  return isValidDate(value) ? value : null;
+}