dayhand 0.0.0-stage → 0.14.0

package/backend/convex/lib/activity.ts

@@ -0,0 +1,155 @@
+// The activity log (list_events, dayhand://activity, dayhand log): the user's
+// task changes in the order they were committed, read from a position on, so
+// an agent back from a pause gets only what changed since its own cursor.
+// Positions are taskEvents.seq (lib/core.ts recordEvent); a cursor is
+// "c<seq>" and means "after this change".
+import type { ObjectType } from "convex/values";
+import type { Doc, Id } from "../_generated/dataModel";
+import type { QueryCtx } from "../_generated/server";
+import type { args } from "./args";
+import { actorLabel, fail, loadTask, type Identity } from "./core";
+
+type Args = ObjectType<(typeof args)["listEvents"]>;
+
+export const MAX_EVENTS = 500;
+const DEFAULT_EVENTS = 100;
+/** Changes looked at per call when filters skip most of them; the cursor continues from there. */
+const SCAN_LIMIT = 4_000;
+
+const CURSOR = /^c(\d{1,17})$/;
+const UNIX_MS = /^\d{1,15}$/;
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/;
+
+export const cursorOf = (seq: number) => `c${seq}`;
+
+/**
+ * The position to read after: a cursor from an earlier call, or a time (Unix
+ * milliseconds or ISO 8601 with a zone) meaning the changes made from then on.
+ */
+function positionOf(since: string): number {
+  const cursor = CURSOR.exec(since);
+  if (cursor) return Number(cursor[1]);
+  const at = UNIX_MS.test(since) ? Number(since) : ISO_TIME.test(since) ? Date.parse(since) : NaN;
+  if (Number.isNaN(at)) {
+    fail("invalid_argument", `since must be a cursor from an earlier call ("c…"), Unix milliseconds or an ISO 8601 time, got "${since}"`);
+  }
+  // Positions start from the change's time in microseconds (lib/core.ts).
+  return at * 1000 - 1;
+}
+
+type ActorFilter = (event: Doc<"taskEvents">) => boolean;
+
+/** "app", "cli", "agent" (any agent) or "agent: <name>" (one key or connection, as history's `by`). */
+function actorFilter(by: string | undefined): ActorFilter {
+  if (by === undefined) return () => true;
+  const wanted = by.trim();
+  if (wanted === "app" || wanted === "cli" || wanted === "agent") return (event) => event.actor === wanted;
+  if (/^agent: .+/.test(wanted)) return (event) => actorLabel(event) === wanted;
+  return fail("invalid_argument", `by must be app, cli, agent or "agent: <name>", got "${by}"`);
+}
+
+function checkLimit(limit: number | undefined): number {
+  if (limit === undefined) return DEFAULT_EVENTS;
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_EVENTS) fail("invalid_argument", `limit must be a whole number from 1 to ${MAX_EVENTS}`);
+  return limit;
+}
+
+async function view(ctx: QueryCtx, event: Doc<"taskEvents">) {
+  const task = event.taskId ? await ctx.db.get(event.taskId) : null;
+  return {
+    id: event._id,
+    at: event.at,
+    taskId: event.taskId ?? null,
+    ref: task?.ref ?? null,
+    title: task?.title ?? null,
+    action: event.action,
+    actor: event.actor,
+    actorName: event.actorName ?? null,
+    by: actorLabel(event),
+    before: event.before ?? null,
+    after: event.after ?? null,
+  };
+}
+
+/** The newest position in the user's log, or 0 before the first task change. */
+async function head(ctx: QueryCtx, userId: string): Promise<number> {
+  const last = await ctx.db
+    .query("taskEvents")
+    .withIndex("by_user_seq", (q) => q.eq("userId", userId).gt("seq", 0))
+    .order("desc")
+    .first();
+  return last?.seq ?? 0;
+}
+
+type Page = { events: Doc<"taskEvents">[]; position: number; hasMore: boolean };
+
+/** Changes after `after`, oldest first; stops at `limit` matches or SCAN_LIMIT looked at. */
+async function forward(ctx: QueryCtx, userId: string, after: number, limit: number, matches: ActorFilter): Promise<Page> {
+  const events: Doc<"taskEvents">[] = [];
+  let position = after;
+  let scanned = 0;
+  for await (const event of ctx.db
+    .query("taskEvents")
+    .withIndex("by_user_seq", (q) => q.eq("userId", userId).gt("seq", after))) {
+    if (events.length >= limit || scanned >= SCAN_LIMIT) return { events, position, hasMore: true };
+    scanned++;
+    position = event.seq!;
+    if (matches(event)) events.push(event);
+  }
+  return { events, position, hasMore: false };
+}
+
+/** The newest `limit` matching changes, oldest first, among the last SCAN_LIMIT. */
+async function latest(ctx: QueryCtx, userId: string, limit: number, matches: ActorFilter): Promise<Page> {
+  const events: Doc<"taskEvents">[] = [];
+  let scanned = 0;
+  for await (const event of ctx.db
+    .query("taskEvents")
+    .withIndex("by_user_seq", (q) => q.eq("userId", userId).gt("seq", 0))
+    .order("desc")) {
+    if (events.length >= limit || scanned >= SCAN_LIMIT) break;
+    scanned++;
+    if (matches(event)) events.push(event);
+  }
+  return { events: events.reverse(), position: await head(ctx, userId), hasMore: false };
+}
+
+/** One task's changes: few enough to read whole, then narrowed like the user's log. */
+async function ofTask(ctx: QueryCtx, userId: string, taskId: Id<"tasks">, after: number | null, limit: number, matches: ActorFilter): Promise<Page> {
+  const all = (
+    await ctx.db
+      .query("taskEvents")
+      .withIndex("by_task", (q) => q.eq("taskId", taskId))
+      .collect()
+  )
+    .filter((e) => e.seq !== undefined && matches(e))
+    .sort((a, b) => a.seq! - b.seq!);
+  if (after === null) return { events: all.slice(-limit), position: await head(ctx, userId), hasMore: false };
+  const rest = all.filter((e) => e.seq! > after);
+  const events = rest.slice(0, limit);
+  const position = events.length > 0 ? events[events.length - 1]!.seq! : Math.max(after, 0);
+  return { events, position, hasMore: rest.length > events.length };
+}
+
+/**
+ * Task changes after `since`, oldest first, with the cursor to pass as
+ * `since` next time. Without `since`: the newest changes and the cursor of
+ * the newest one, to start following the log from now.
+ */
+export async function listEvents(ctx: QueryCtx, identity: Identity, input: Args) {
+  const limit = checkLimit(input.limit);
+  const matches = actorFilter(input.by);
+  const after = input.since === undefined ? null : positionOf(input.since.trim());
+  let page: Page;
+  if (input.taskId !== undefined) {
+    const task = await loadTask(ctx, identity.userId, input.taskId);
+    page = await ofTask(ctx, identity.userId, task._id, after, limit, matches);
+  } else if (after === null) {
+    page = await latest(ctx, identity.userId, limit, matches);
+  } else {
+    page = await forward(ctx, identity.userId, after, limit, matches);
+  }
+  const events = [];
+  for (const event of page.events) events.push(await view(ctx, event));
+  return { events, nextCursor: cursorOf(Math.max(page.position, 0)), hasMore: page.hasMore };
+}

package/backend/convex/lib/agentControls.ts

@@ -0,0 +1,146 @@
+// The owner's controls over agents (docs/agent-work.md#6-pausing-agents-and-tool-policies):
+// one switch that pauses every agent, and per agent key a rule for each write
+// tool: allow, ask (an approval request first, lib/approvals.ts) or deny. Reads
+// are never refused. Every change an agent makes passes gateAgentWrite, in the
+// same transaction as the change (ops.ts).
+import type { ObjectType } from "convex/values";
+import type { Doc, Id } from "../_generated/dataModel";
+import type { MutationCtx, QueryCtx } from "../_generated/server";
+import type { args } from "./args";
+import { usePolicyApproval } from "./approvals";
+import { fail, ownerOnly, recordEvent, type Identity } from "./core";
+import type { PolicyRule } from "./validators";
+
+type Args<K extends keyof typeof args> = ObjectType<(typeof args)[K]>;
+
+const MAX_REASON = 500;
+/** The rule of every write tool of a key that has no rule of its own. */
+export const ANY_TOOL = "*";
+
+async function controlsRow(ctx: QueryCtx, userId: string) {
+  return ctx.db
+    .query("agentControls")
+    .withIndex("by_user", (q) => q.eq("userId", userId))
+    .unique();
+}
+
+/** The rule for one key and one write tool: its own row, else the key's "*" row, else allow. */
+export async function ruleOf(ctx: QueryCtx, keyId: Id<"apiKeys">, tool: string): Promise<PolicyRule> {
+  for (const name of [tool, ANY_TOOL]) {
+    const row = await ctx.db
+      .query("toolPolicies")
+      .withIndex("by_key_tool", (q) => q.eq("keyId", keyId).eq("tool", name))
+      .unique();
+    if (row) return row.rule;
+  }
+  return "allow";
+}
+
+/**
+ * Refuses a change by an agent while agents are paused, or when the owner's
+ * policy denies the tool to its key; with "ask" the call needs an approval
+ * request decided "allow" (approvalId), used up by this change. A dry run
+ * changes nothing and needs no approval. The owner (app, cli) is never refused.
+ */
+export async function gateAgentWrite(
+  ctx: MutationCtx,
+  identity: Identity,
+  call: { tool?: string; approvalId?: string; dryRun?: boolean; input: Record<string, unknown> },
+) {
+  if (identity.actor !== "agent") return;
+  const controls = await controlsRow(ctx, identity.userId);
+  if (controls?.pausedAt !== undefined) {
+    const reason = controls.reason ? ` (${controls.reason})` : "";
+    fail("agents_paused", `The owner has paused all agents${reason}: reading works, changes are refused until they resume agents`);
+  }
+  if (!call.tool || !identity.keyId) return;
+  const rule = await ruleOf(ctx, identity.keyId, call.tool);
+  if (rule === "deny") fail("forbidden", `The owner's policy does not let this key call ${call.tool}`);
+  if (rule === "allow" || call.dryRun) return;
+  if (call.approvalId === undefined) {
+    fail("approval_required", `The owner's policy asks before this key calls ${call.tool}`);
+  }
+  await usePolicyApproval(ctx, identity, call.tool, call.input, call.approvalId);
+}
+
+/** Whether agents are paused: for the account routes of the REST API, which run no domain change. */
+export async function agentsPaused(ctx: QueryCtx, userId: string): Promise<boolean> {
+  return (await controlsRow(ctx, userId))?.pausedAt !== undefined;
+}
+
+// ---- Views and the owner's changes ----
+
+async function policyViews(ctx: QueryCtx, userId: string) {
+  const rows = await ctx.db
+    .query("toolPolicies")
+    .withIndex("by_user", (q) => q.eq("userId", userId))
+    .collect();
+  const keys = new Map<string, Doc<"apiKeys"> | null>();
+  for (const row of rows) if (!keys.has(row.keyId)) keys.set(row.keyId, await ctx.db.get(row.keyId));
+  return rows
+    .filter((row) => keys.get(row.keyId)?.revokedAt === undefined && keys.get(row.keyId) !== null)
+    .map((row) => ({ keyId: row.keyId, keyName: keys.get(row.keyId)!.name, tool: row.tool, rule: row.rule, updatedAt: row.updatedAt }))
+    .sort((a, b) => a.keyName.localeCompare(b.keyName) || a.tool.localeCompare(b.tool));
+}
+
+/** get_agent_controls: whether agents are paused, and every rule the owner set. */
+export async function getAgentControls(ctx: QueryCtx, identity: Identity) {
+  const row = await controlsRow(ctx, identity.userId);
+  const paused = row?.pausedAt !== undefined;
+  return {
+    paused,
+    pausedAt: row?.pausedAt ?? null,
+    pausedBy: paused ? (row?.pausedBy ?? null) : null,
+    reason: paused ? (row?.reason ?? null) : null,
+    policies: await policyViews(ctx, identity.userId),
+  };
+}
+
+/** pause_agents: the owner pauses every agent, or lets them run again. */
+export async function setAgentsPaused(ctx: MutationCtx, identity: Identity, input: Args<"pauseAgents">) {
+  ownerOnly(identity, "pause or resume agents");
+  const reason = input.reason?.trim();
+  if (reason && reason.length > MAX_REASON) fail("invalid_argument", `reason is longer than ${MAX_REASON} characters`);
+  const row = await controlsRow(ctx, identity.userId);
+  const now = Date.now();
+  const wasPaused = row?.pausedAt !== undefined;
+  const fields = input.paused
+    ? { pausedAt: wasPaused ? row!.pausedAt : now, pausedBy: identity.actor, reason: reason || undefined, updatedAt: now }
+    : { pausedAt: undefined, pausedBy: undefined, reason: undefined, updatedAt: now };
+  if (row) await ctx.db.patch(row._id, fields);
+  else await ctx.db.insert("agentControls", { userId: identity.userId, ...fields });
+  if (wasPaused !== input.paused) {
+    await recordEvent(ctx, identity, { action: input.paused ? "agents.pause" : "agents.resume", after: input.paused ? { reason: reason ?? null } : {} });
+  }
+  return getAgentControls(ctx, identity);
+}
+
+/** set_tool_policy: the owner's rule for one agent key and one write tool (or "*"); allow removes the rule. */
+export async function setToolPolicy(ctx: MutationCtx, identity: Identity, input: Args<"setToolPolicy">, writeTools: readonly string[]) {
+  ownerOnly(identity, "change tool policies");
+  const keyId = ctx.db.normalizeId("apiKeys", input.apiKeyId);
+  const key = keyId ? await ctx.db.get(keyId) : null;
+  if (!keyId || !key || key.userId !== identity.userId || key.revokedAt !== undefined) fail("not_found", `API key ${input.apiKeyId} not found`);
+  if ((key.kind ?? "agent") !== "agent") fail("invalid_argument", "Policies are for agent keys; a cli key is the owner at a terminal");
+  const tool = input.toolName;
+  if (tool !== ANY_TOOL && !writeTools.includes(tool)) {
+    fail("invalid_argument", `toolName must be "*" or a tool that changes the plan: ${writeTools.join(", ")}`);
+  }
+  const existing = await ctx.db
+    .query("toolPolicies")
+    .withIndex("by_key_tool", (q) => q.eq("keyId", keyId).eq("tool", tool))
+    .unique();
+  const before = existing?.rule ?? null;
+  // "allow" on a single tool is kept when the key's "*" rule says otherwise; otherwise allow is the default.
+  const keepAllow = input.rule === "allow" && tool !== ANY_TOOL && (await ruleOf(ctx, keyId, ANY_TOOL)) !== "allow";
+  if (input.rule === "allow" && !keepAllow) {
+    if (existing) await ctx.db.delete(existing._id);
+  } else if (existing) {
+    if (existing.rule !== input.rule) await ctx.db.patch(existing._id, { rule: input.rule, updatedAt: Date.now() });
+  }
+  else await ctx.db.insert("toolPolicies", { userId: identity.userId, keyId, tool, rule: input.rule, updatedAt: Date.now() });
+  if (before !== input.rule) {
+    await recordEvent(ctx, identity, { action: "policy.set", before: { rule: before }, after: { keyId, keyName: key.name, tool, rule: input.rule } });
+  }
+  return getAgentControls(ctx, identity);
+}

package/backend/convex/lib/agentWork.ts

@@ -0,0 +1,250 @@
+// Agent work on a task (docs/agent-work.md): acceptance criteria and a plan,
+// proof of completion, dependencies and a blocked reason, and a time-boxed
+// claim. No new statuses: everything here is fields next to todo/doing/done.
+import type { ObjectType } from "convex/values";
+import type { Doc, Id } from "../_generated/dataModel";
+import type { MutationCtx, QueryCtx } from "../_generated/server";
+import type { args } from "./args";
+import { checkLinks, checkText, fail, loadTask, patchTask, replay, toTask, type Identity } from "./core";
+import type { AcceptanceInput, AcceptanceItem, ClaimHolder, Proof } from "./validators";
+
+type Args<K extends keyof typeof args> = ObjectType<(typeof args)[K]>;
+
+const LIMITS = {
+  acceptance: 50,
+  acceptanceId: 64,
+  acceptanceText: 500,
+  plan: 20_000,
+  blockedReason: 2_000,
+  dependsOn: 50,
+  summary: 4_000,
+  checks: 50,
+  checkName: 200,
+  url: 2_048,
+  claimMinutes: 24 * 60,
+};
+
+export const DEFAULT_CLAIM_MINUTES = 120;
+
+// ---- Acceptance criteria, plan, blocked reason ----
+
+/**
+ * The criteria as stored: trimmed texts in the given order, `met` false unless
+ * set, and an id for every one. New criteria get the next free `a<n>`. An
+ * empty list is no criteria.
+ */
+export function checkAcceptance(items: AcceptanceInput[]): AcceptanceItem[] | undefined {
+  if (items.length > LIMITS.acceptance) fail("invalid_argument", `at most ${LIMITS.acceptance} acceptance criteria`);
+  const given = items.map((item) => item.id).filter((id): id is string => id !== undefined);
+  if (given.some((id) => id.trim() === "" || id.length > LIMITS.acceptanceId)) {
+    fail("invalid_argument", `acceptance criterion ids must be 1 to ${LIMITS.acceptanceId} characters`);
+  }
+  if (new Set(given).size !== given.length) fail("invalid_argument", "acceptance criterion ids must be distinct");
+  const used = new Set(given);
+  let next = 1;
+  const freeId = () => {
+    while (used.has(`a${next}`)) next++;
+    used.add(`a${next}`);
+    return `a${next}`;
+  };
+  const result = items.map((item) => {
+    const text = item.text.trim();
+    if (!text) fail("invalid_argument", "acceptance criteria need a text");
+    if (text.length > LIMITS.acceptanceText) fail("invalid_argument", `acceptance criteria are at most ${LIMITS.acceptanceText} characters`);
+    return { id: item.id ?? freeId(), text, met: item.met ?? false };
+  });
+  return result.length > 0 ? result : undefined;
+}
+
+export function checkLongText(field: "plan" | "blockedReason", value: string): string | undefined {
+  if (value.length > LIMITS[field]) fail("invalid_argument", `${field} is longer than ${LIMITS[field]} characters`);
+  return value.trim() === "" ? undefined : value;
+}
+
+// ---- Proof of completion ----
+
+function checkUrl(field: string, url: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    fail("invalid_argument", `${field}: invalid URL "${url}"`);
+  }
+  if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") || url.length > LIMITS.url) {
+    fail("invalid_argument", `${field}: URLs must be http(s), up to ${LIMITS.url} characters`);
+  }
+  return url;
+}
+
+/** The proof as stored: a trimmed summary, checked links and checks; empty parts left out. */
+export function checkProof(proof: Proof): Proof {
+  const summary = proof.summary?.trim();
+  if (summary && summary.length > LIMITS.summary) fail("invalid_argument", `proof.summary is longer than ${LIMITS.summary} characters`);
+  const checks = proof.checks ?? [];
+  if (checks.length > LIMITS.checks) fail("invalid_argument", `at most ${LIMITS.checks} proof checks`);
+  const cleanChecks = checks.map((check) => {
+    const name = check.name.trim();
+    if (!name || name.length > LIMITS.checkName) fail("invalid_argument", `proof checks need a name of 1 to ${LIMITS.checkName} characters`);
+    return check.url === undefined ? { name, result: check.result } : { name, result: check.result, url: checkUrl("proof.checks", check.url) };
+  });
+  return {
+    ...(summary ? { summary } : {}),
+    links: checkLinks(proof.links ?? []),
+    checks: cleanChecks,
+  };
+}
+
+/**
+ * An agent may complete a task with acceptance criteria only when every
+ * criterion is met and the proof has a summary. People (app, cli) complete
+ * tasks as before.
+ */
+export function checkCompletion(task: Doc<"tasks">, identity: Identity, proof: Proof | undefined) {
+  const criteria = task.acceptance ?? [];
+  if (identity.actor !== "agent" || criteria.length === 0) return;
+  const unmet = criteria.filter((item) => !item.met);
+  if (unmet.length > 0) {
+    fail("precondition_failed", `Acceptance criteria not met: ${unmet.map((item) => item.id).join(", ")}; mark them met with update_task first`);
+  }
+  if (!proof?.summary) fail("precondition_failed", "A task with acceptance criteria needs proof with a summary to be completed by an agent");
+}
+
+// ---- Dependencies ----
+
+/**
+ * The dependencies as stored: the tasks' ids, each once. A task cannot depend
+ * on itself or on a task that (through its own dependencies) depends on it.
+ */
+export async function checkDependsOn(ctx: QueryCtx, userId: string, taskId: Id<"tasks"> | null, refs: string[]): Promise<Id<"tasks">[] | undefined> {
+  if (refs.length > LIMITS.dependsOn) fail("invalid_argument", `at most ${LIMITS.dependsOn} dependencies`);
+  const ids: Id<"tasks">[] = [];
+  for (const ref of refs) {
+    const dependency = await loadTask(ctx, userId, ref);
+    if (dependency._id === taskId) fail("invalid_argument", "A task cannot depend on itself");
+    if (!ids.includes(dependency._id)) ids.push(dependency._id);
+  }
+  if (taskId !== null) await refuseCycle(ctx, taskId, ids);
+  return ids.length > 0 ? ids : undefined;
+}
+
+async function refuseCycle(ctx: QueryCtx, taskId: Id<"tasks">, start: Id<"tasks">[]) {
+  const seen = new Set<string>();
+  const pending = [...start];
+  while (pending.length > 0) {
+    const id = pending.pop()!;
+    if (id === taskId) fail("invalid_argument", "These dependencies would make a cycle: a task would wait for itself");
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const task = await ctx.db.get(id);
+    pending.push(...(task?.dependsOn ?? []));
+  }
+}
+
+/**
+ * Ready to work on: not done, not blocked, not a proposal, and every dependency
+ * done. A dependency in the trash or purged no longer holds the task back.
+ */
+export function isReady(task: Doc<"tasks">, byId: Map<string, Doc<"tasks">>): boolean {
+  if (task.status === "done" || task.blockedReason !== undefined || task.proposedAt !== undefined) return false;
+  return (task.dependsOn ?? []).every((id) => {
+    const dependency = byId.get(id);
+    return dependency === undefined || dependency.deletedAt !== undefined || dependency.status === "done";
+  });
+}
+
+// ---- Claims ----
+
+/** The caller as a claim holder; only an API key or an agent connection can hold a claim. */
+function holderOf(identity: Identity): ClaimHolder {
+  if (identity.keyId) return { keyId: identity.keyId, name: identity.actorName ?? "API key" };
+  if (identity.connectionId) return { connectionId: identity.connectionId, name: identity.actorName ?? "connection" };
+  return fail("invalid_argument", "Only an API key or an agent connection can claim a task");
+}
+
+/** Whether the caller (its API key or agent connection) is the holder. */
+export const sameHolder = (a: ClaimHolder | undefined, identity: Pick<Identity, "keyId" | "connectionId">) =>
+  a !== undefined && ((a.keyId !== undefined && a.keyId === identity.keyId) || (a.connectionId !== undefined && a.connectionId === identity.connectionId));
+
+/** The live claim of someone other than the caller, if any. */
+function othersClaim(task: Doc<"tasks">, identity: Identity, now: number): ClaimHolder | null {
+  const live = task.claimedBy !== undefined && (task.claimExpiresAt ?? 0) > now;
+  return live && !sameHolder(task.claimedBy, identity) ? task.claimedBy! : null;
+}
+
+const until = (at: number) => new Date(at).toISOString();
+
+function conflict(task: Doc<"tasks">, holder: ClaimHolder): never {
+  fail("conflict", `Task #${task.ref ?? task._id} is claimed by ${holder.name} until ${until(task.claimExpiresAt!)}`);
+}
+
+/**
+ * Refuses a change of a task that another agent has claimed. The owner wins:
+ * changes from the app and the CLI (the user) always go through.
+ */
+export function checkClaim(task: Doc<"tasks">, identity: Identity) {
+  if (identity.actor !== "agent") return;
+  const holder = othersClaim(task, identity, Date.now());
+  if (holder) conflict(task, holder);
+}
+
+function claimMinutes(minutes: number | undefined): number {
+  const value = minutes ?? DEFAULT_CLAIM_MINUTES;
+  if (!Number.isInteger(value) || value < 1 || value > LIMITS.claimMinutes) {
+    fail("invalid_argument", `minutes must be a whole number from 1 to ${LIMITS.claimMinutes}`);
+  }
+  return value;
+}
+
+function claimable(task: Doc<"tasks">) {
+  if (task.deletedAt !== undefined) fail("invalid_argument", "Task is in the trash; restore it first");
+  if (task.archivedAt !== undefined) fail("invalid_argument", "Task is archived; restore it first");
+  if (task.status === "done") fail("invalid_argument", "Task is done; reopen it first");
+  if (task.proposedAt !== undefined) fail("invalid_argument", "Task is a proposal; it can be claimed once the owner accepts it");
+  return task;
+}
+
+/** Claims a task for `minutes` (default 120); claiming it again extends the caller's own claim. */
+export async function claimTask(ctx: MutationCtx, identity: Identity, input: Args<"claim">) {
+  const replayed = await replay(ctx, identity.userId, input.clientId);
+  if (replayed) return toTask(replayed);
+  const task = claimable(await loadTask(ctx, identity.userId, input.taskId));
+  const holder = holderOf(identity);
+  const minutes = claimMinutes(input.minutes);
+  const other = othersClaim(task, identity, Date.now());
+  if (other) conflict(task, other);
+  const patch = { claimedBy: holder, claimExpiresAt: Date.now() + minutes * 60_000 };
+  return toTask(await patchTask(ctx, identity, task, "claim", patch, input.clientId));
+}
+
+/**
+ * Extends the caller's claim by `minutes` from now. It works after the claim
+ * expired too, as long as nobody else has claimed the task since.
+ */
+export async function renewClaim(ctx: MutationCtx, identity: Identity, input: Args<"renewClaim">) {
+  const replayed = await replay(ctx, identity.userId, input.clientId);
+  if (replayed) return toTask(replayed);
+  const task = claimable(await loadTask(ctx, identity.userId, input.taskId));
+  const minutes = claimMinutes(input.minutes);
+  if (!sameHolder(task.claimedBy, identity)) {
+    const other = othersClaim(task, identity, Date.now());
+    if (other) conflict(task, other);
+    fail("precondition_failed", "You do not hold a claim on this task; claim it with claim_task");
+  }
+  return toTask(await patchTask(ctx, identity, task, "renewClaim", { claimExpiresAt: Date.now() + minutes * 60_000 }, input.clientId));
+}
+
+/**
+ * Gives a claim up, optionally leaving a checkpoint as the resume note (where
+ * the work stopped, the next step). The holder releases its own claim; the
+ * owner (app, cli) may release anyone's, which is how a person takes over.
+ */
+export async function releaseTask(ctx: MutationCtx, identity: Identity, input: Args<"release">) {
+  const replayed = await replay(ctx, identity.userId, input.clientId);
+  if (replayed) return toTask(replayed);
+  const task = await loadTask(ctx, identity.userId, input.taskId);
+  checkClaim(task, identity);
+  const patch: Partial<Doc<"tasks">> = { claimedBy: undefined, claimExpiresAt: undefined };
+  const checkpoint = input.note === undefined ? undefined : checkText("resumeNote", input.note);
+  if (checkpoint !== undefined) patch.resumeNote = checkpoint;
+  return toTask(await patchTask(ctx, identity, task, "release", patch, input.clientId));
+}

package/backend/convex/lib/appToken.ts

@@ -0,0 +1,68 @@
+// Signs the app's ES256 JWT inside the deployment. The private key is the
+// deployment environment variable DAYHAND_JWT_PRIVATE_JWK (a JWK with `kid`);
+// its public half must be the key with the same `kid` in DAYHAND_JWKS, which
+// auth.config.ts trusts. The private key is never returned to any client.
+import { serverEnv } from "./env";
+import { bytesToBase64url } from "./secrets";
+
+export const APP_TOKEN_TTL_SECONDS = 3600;
+const AUDIENCE = "helm";
+const ALGORITHM = { name: "ECDSA", namedCurve: "P-256" };
+
+export type SigningConfig = { issuer: string; privateJwk: JsonWebKey & { kid: string } };
+
+export class SigningConfigError extends Error {}
+
+function decodeJwks(dataUri: string): { keys: (JsonWebKey & { kid?: string })[] } {
+  const match = /^data:application\/json;base64,(.+)$/.exec(dataUri);
+  if (!match) throw new SigningConfigError("DAYHAND_JWKS is not a base64 JSON data URI");
+  return JSON.parse(atob(match[1]));
+}
+
+/** Reads and cross-checks the signing configuration; throws SigningConfigError when unusable. */
+export function signingConfig(): SigningConfig {
+  const issuer = serverEnv("JWT_ISSUER");
+  const rawKey = serverEnv("JWT_PRIVATE_JWK");
+  const jwks = serverEnv("JWKS");
+  if (!issuer || !rawKey || !jwks) {
+    throw new SigningConfigError("DAYHAND_JWT_ISSUER, DAYHAND_JWT_PRIVATE_JWK and DAYHAND_JWKS must all be set");
+  }
+  let privateJwk: JsonWebKey & { kid?: string };
+  try {
+    privateJwk = JSON.parse(rawKey);
+  } catch {
+    throw new SigningConfigError("DAYHAND_JWT_PRIVATE_JWK is not JSON");
+  }
+  const { kty, crv, d, x, y, kid } = privateJwk;
+  if (kty !== "EC" || crv !== "P-256" || !d || !x || !y || !kid) {
+    throw new SigningConfigError("DAYHAND_JWT_PRIVATE_JWK must be a P-256 EC private JWK with a kid");
+  }
+  const published = decodeJwks(jwks).keys.find((k) => k.kid === kid);
+  if (!published || published.x !== x || published.y !== y) {
+    throw new SigningConfigError("DAYHAND_JWT_PRIVATE_JWK does not match the key with its kid in DAYHAND_JWKS");
+  }
+  return { issuer, privateJwk: { ...privateJwk, kid } };
+}
+
+/** The JWT subject for a Dayhand user id `<issuer>|<subject>`; null for any other user id. */
+export function appSubject(userId: string, issuer: string): string | null {
+  const prefix = `${issuer}|`;
+  return userId.startsWith(prefix) && userId.length > prefix.length ? userId.slice(prefix.length) : null;
+}
+
+const encodeJson = (value: unknown) => bytesToBase64url(new TextEncoder().encode(JSON.stringify(value)));
+
+export async function signAppToken(config: SigningConfig, subject: string, nowMs = Date.now()) {
+  const { kty, crv, d, x, y } = config.privateJwk;
+  const key = await crypto.subtle.importKey("jwk", { kty, crv, d, x, y }, ALGORITHM, false, ["sign"]);
+  const iat = Math.floor(nowMs / 1000);
+  const exp = iat + APP_TOKEN_TTL_SECONDS;
+  const header = encodeJson({ alg: "ES256", typ: "JWT", kid: config.privateJwk.kid });
+  const payload = encodeJson({ iss: config.issuer, sub: subject, aud: AUDIENCE, iat, exp });
+  const signature = await crypto.subtle.sign(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    new TextEncoder().encode(`${header}.${payload}`),
+  );
+  return { token: `${header}.${payload}.${bytesToBase64url(new Uint8Array(signature))}`, expiresAt: exp * 1000 };
+}