toolroll 0.9.103 → 0.9.105

package/dist/lead-voice.js

@@ -1,10 +1,3 @@
-/** The lead's voice: what the person's lead (an agent under their lead token) is doing, in their chat and on the
- * console. `lead say` posts one short message from the lead, by the name its person gave it (Settings → Lead); several within two minutes are one message, edited
- * in place as it grows. `assignment claim` marks a task the lead's: it reads "<name> is on it" and leaves Needs
- * you until the lead completes it, hands it to a person, or two hours pass with no lead act on it.
- *
- * Every fact is an append-only ledger row under "lead for <owner>"; no table of its own. The chat message is an
- * ordinary notification addressed to the owner, so every chat delivers it with the usual receipts. */
 import { actorLabel, withActor } from "./actor.js";
 import { chatControlHref } from "./chat-controls.js";
 import { BATCH_MS, chatText, chatTitle } from "./chat-voice.js";
@@ -13,24 +6,16 @@ import { leadNameOf } from "./lead-identity.js";
 import { leadLapsed } from "./task-status.js";
 import { publicChatText as plain } from "./chat-display.js";
 export const LEAD_SAY_KIND = "lead-say";
-/** Repaints the owner's task card when the lead takes a task on: it never makes a new message in quiet chat. */
 export const LEAD_ON_IT_KIND = "lead-on-it";
-/** Repaints the owner's task card when a claim lapses: the card reads its real state again, and says so. */
 export const LEAD_LAPSED_KIND = "lead-lapsed";
 export const LEAD_SAID = "lead said";
 export const LEAD_CLAIMED = "lead is on it";
-/** A claim lapses after this long without a lead act on the task. */
 export const LEAD_IDLE_MS = 2 * 3_600_000;
-/** The lead's acts that hand the task back: done, handed to a person, or cancelled. */
 export const LEAD_ENDS = ["task completed", "task handed to a person", "task cancelled"];
-/** Acts by anyone that end a claim: a completed or cancelled task is nobody's to be on. */
 const DONE_ACTS_SQL = "'completed','cancelled'";
 export const LEAD_SAY_MAX = 300;
-/** Lines one batched message keeps; the oldest go first. */
 const BATCH_LINES = 8;
 const ENDS_SQL = LEAD_ENDS.map(one => `'${one}'`).join(",");
-/** The work index's reading of a claim, per row of its `classified` projection: 0 none, 1 on it, 2 lapsed. Only the
- * viewer's own lead counts (`$leadOf`, "lead for <viewer>"; null for nobody): another person's lead is not yours. */
 export const LEAD_CLAIM_SQL = `COALESCE((SELECT CASE
       WHEN EXISTS(SELECT 1 FROM action_ledger e WHERE e.task_id IN (SELECT m.id FROM ordered m WHERE m.root_ref = c.root_ref)
         AND e.id > claim.id AND e.actor = claim.actor AND e.action IN (${ENDS_SQL})) THEN 0
@@ -39,7 +24,6 @@ export const LEAD_CLAIM_SQL = `COALESCE((SELECT CASE
       WHEN (SELECT MAX(a.at) FROM action_ledger a WHERE a.task_id IN (SELECT m.id FROM ordered m WHERE m.root_ref = c.root_ref)
         AND a.id >= claim.id AND a.actor = claim.actor) > $leadIdleSince THEN 1 ELSE 2 END
     FROM action_ledger claim WHERE claim.id = (SELECT MAX(id) FROM action_ledger WHERE task_id = c.root_id AND action = '${LEAD_CLAIMED}' AND actor = $leadOf)), 0)`;
-/** A task family's root and every version, following revisions both ways. */
 function familyOf(store, taskId) {
     const root = store.handle.prepare(`WITH RECURSIVE up(id, depth) AS (SELECT ?, 0 UNION ALL
       SELECT r.revision_of, up.depth + 1 FROM up JOIN task_ref r ON r.backend = ? AND r.external_id = up.id WHERE r.revision_of IS NOT NULL AND up.depth < 64)
@@ -50,7 +34,6 @@ function familyOf(store, taskId) {
     SELECT DISTINCT id FROM down`).all(top, BUILT_IN).map(row => String(row["id"]));
     return { root: top, ids };
 }
-/** One line of the lead's words: plain, short, no control characters. */
 export function leadWordsProblem(text) {
     const words = text.trim();
     if (words === "")
@@ -61,7 +44,6 @@ export function leadWordsProblem(text) {
         return "One line of plain text.";
     return null;
 }
-/** The task the lead names, if its owner can see it. */
 function admittedTask(store, owner, taskId) {
     const ref = store.lookupRef(taskId);
     if (ref === null || store.getTask(taskId) === null)
@@ -70,9 +52,6 @@ function admittedTask(store, owner, taskId) {
         return { ok: false, reason: "unknown-task", message: `No task \`${taskId}\`.` };
     return { refId: ref.id, repo: ref.repo };
 }
-/** `lead say`: record the words as the lead's act, and post them in the owner's chat. Within two minutes of the
- * first, a later say joins it: the new row carries every line, and the earlier one stops waiting to be sent (a
- * chat that already showed it edits that message in place). */
 export function leadSay(store, actor, text, taskId, now) {
     if (!actor.lead)
         return { ok: false, reason: "refused", message: "Only the lead speaks as the lead: pass its lead token." };
@@ -82,10 +61,8 @@ export function leadSay(store, actor, text, taskId, now) {
     const task = taskId === null ? null : admittedTask(store, actor.account, taskId);
     if (task !== null && "ok" in task)
         return task;
-    // The task's own id never reaches a chat: it reads as the task's short title (chat-voice.ts).
     const said = taskId === null ? text.trim() : chatText(text.trim(), [{ id: taskId, title: chatTitle(store, taskId) }]);
     return store.transact(() => {
-        // A put-away task (v145) gets no messages: the lead's words about it would nudge a person about nothing.
         if (task !== null && refArchived(store, task.refId))
             return { ok: false, reason: "refused", message: "This task is put away. A person can restore it first." };
         const stamp = now.toISOString();
@@ -94,7 +71,6 @@ export function leadSay(store, actor, text, taskId, now) {
         const open = store.handle.prepare(`SELECT id, dedupe_key, body, task_ref FROM notification WHERE kind = ? AND recipient = ? ORDER BY id DESC LIMIT 1`)
             .get(LEAD_SAY_KIND, actor.account);
         const opened = open === undefined ? null : /^lead-say:(.+):\d+$/.exec(String(open["dedupe_key"]))?.[1] ?? null;
-        // A batch is about one task (or none): words about another start a row of their own, so each row keeps its task.
         const sameTask = open !== undefined && (open["task_ref"] ?? null) === (task === null ? null : task.refId);
         const joined = sameTask && opened !== null && Date.parse(opened) > now.getTime() - BATCH_MS && Date.parse(opened) <= now.getTime();
         const lines = [...(joined ? String(open["body"]).split("\n") : []), said].slice(-BATCH_LINES);
@@ -107,9 +83,6 @@ export function leadSay(store, actor, text, taskId, now) {
         return { ok: true, joined, notification: row === undefined ? null : Number(row["id"]) };
     });
 }
-/** A lead row's subject in its owner's current name for their lead, read when it is shown, so a rename reaches
- * earlier cards too; any other row's own subject. `reader`: who the chat belongs to, for a row with no recipient
- * (only its owner ever receives a lead row). */
 export function leadSubjectOf(store, row, reader) {
     const owner = row.recipient ?? reader ?? null;
     if (owner === null || (row.kind !== LEAD_SAY_KIND && row.kind !== LEAD_ON_IT_KIND && row.kind !== LEAD_LAPSED_KIND))
@@ -117,12 +90,9 @@ export function leadSubjectOf(store, row, reader) {
     const name = leadNameOf(store, owner);
     return row.kind === LEAD_SAY_KIND ? name : row.kind === LEAD_ON_IT_KIND ? `${name} is on it` : leadLapsed(name);
 }
-/** The words a chat shows for a lead-say row: the lead's name, then each line, plain, with no task id. `reader`: whose
- * chat it is, for a row with no recipient (see leadSubjectOf). */
 export function leadSayText(store, row, reader) {
     return chatText([plain(leadSubjectOf(store, row, reader), 60), "", ...row.body.split("\n").map(line => plain(line, LEAD_SAY_MAX)).filter(line => line !== "")].join("\n"));
 }
-/** The earlier rows of a lead-say message (newest first): a chat that showed one edits it rather than sending again. */
 export function leadSayEarlier(store, row) {
     if (row.kind !== LEAD_SAY_KIND || row.recipient === null)
         return [];
@@ -132,8 +102,6 @@ export function leadSayEarlier(store, row) {
     return store.handle.prepare(`SELECT id FROM notification WHERE kind = ? AND recipient = ? AND id < ? AND substr(dedupe_key, 1, ?) = ? ORDER BY id DESC`)
         .all(LEAD_SAY_KIND, row.recipient, row.id, opened.length, opened).map(one => Number(one["id"]));
 }
-/** `assignment claim` under the lead token: the task is the lead's until it completes it, hands it on, or goes
- * quiet on it for two hours. Repeating a claim is safe and counts as a lead act. */
 export function leadClaim(store, actor, taskId, now) {
     if (!actor.lead)
         return { ok: false, reason: "refused", message: "Only the lead takes a task on as the lead: pass its lead token." };
@@ -142,13 +110,10 @@ export function leadClaim(store, actor, taskId, now) {
         return task;
     const { root } = familyOf(store, taskId);
     const taken = store.transact(() => {
-        // A put-away task (v145) waits on nobody, so the lead takes nothing on there: checked with the claim's own write.
         if (refArchived(store, task.refId))
             return false;
         const ledger = store.recordAction({ at: now.toISOString(), actor: actorLabel(actor), repo: task.repo, taskId: root, runId: null,
             action: LEAD_CLAIMED, outcome: "recorded", source: "work" });
-        // The owner's card for this task repaints to "<name> is on it": quiet chat edits its card, and every-update
-        // chat edits the attempt's own card (the Failed alert), or follows it up when that message is gone.
         store.enqueueNotification({ dedupeKey: `lead-on-it:${ledger}`, kind: LEAD_ON_IT_KIND, subject: `${leadNameOf(store, actor.account)} is on it`, body: "",
             link: chatControlHref("task", taskId), source: cardSource(store, root) ?? { taskRef: task.refId } }, now);
         return true;
@@ -157,8 +122,6 @@ export function leadClaim(store, actor, taskId, now) {
         return { ok: false, reason: "refused", message: "This task is put away. A person can restore it first." };
     return { ok: true, root, claim: leadClaimOf(store, taskId, now, actor.account) };
 }
-/** Where a task's chat card lives: the family's newest attempt (the card every-update chat edits), else its newest
- * version. Null for a task with no reference. */
 function cardSource(store, root) {
     const refs = familyOf(store, root).ids.map(id => store.lookupRef(id)).filter(ref => ref !== null).sort((a, b) => b.id - a.id);
     const newest = refs[0];
@@ -168,8 +131,6 @@ function cardSource(store, root) {
     const run = runs.reduce((top, one) => top === null || one.id > top ? one.id : top, null);
     return run === null ? { taskRef: newest.id } : { run };
 }
-/** Whether anyone completed or cancelled the task family (since `since`, when given), or its newest version is
- * cancelled however that happened: a finished task is nobody's to be on. */
 function familyEnded(store, ids, since) {
     const refs = ids.map(id => store.lookupRef(id)).filter(ref => ref !== null).sort((a, b) => b.id - a.id);
     if (refs[0] === undefined)
@@ -179,8 +140,6 @@ function familyEnded(store, ids, since) {
     return store.handle.prepare(`SELECT 1 AS hit FROM task_act WHERE task_ref IN (${refs.map(() => "?").join(",")}) AND act IN (${DONE_ACTS_SQL})
     AND at >= ? LIMIT 1`).get(...refs.map(ref => ref.id), since ?? "") !== undefined;
 }
-/** Whether `viewer`'s own lead has this task now: on it, lapsed after two quiet hours (it says so), or null (never
- * claimed by their lead, handed on by it since, or completed or cancelled by anyone). Another person's lead never counts. */
 export function leadClaimOf(store, taskId, now, viewer) {
     if (viewer == null || viewer === "")
         return null;
@@ -192,7 +151,6 @@ export function leadClaimOf(store, taskId, now, viewer) {
             return null;
         const family = `task_id IN (${ids.map(() => "?").join(",")}) AND id >= ? AND actor = ?`;
         const args = [...ids, Number(claim["id"]), String(claim["actor"])];
-        // Completed, handed on or cancelled by the lead since its claim: the claim is over.
         if (store.handle.prepare(`SELECT 1 AS hit FROM action_ledger WHERE ${family} AND action IN (${ENDS_SQL}) LIMIT 1`).get(...args) !== undefined)
             return null;
         if (familyEnded(store, ids, String(claim["at"])))
@@ -203,13 +161,9 @@ export function leadClaimOf(store, taskId, now, viewer) {
             owner: String(claim["actor"]).replace(/^lead for /, ""), since: String(claim["at"]), lastActedAt };
     }
     catch {
-        // An older store being read by a newer build: no claim is the safe reading.
         return null;
     }
 }
-/** A claim that lapsed repaints its owner's card once per lapse: the card reads the task's real state again and
- * says it is back with them. Run beside the evening digests on every chat pass; claims are found through their
- * repaint rows (an indexed key range), so nothing scans the ledger. */
 export function enqueueLeadLapses(store, now) {
     let count = 0;
     try {
@@ -223,24 +177,20 @@ export function enqueueLeadLapses(store, now) {
             if (claim?.state !== "lapsed")
                 continue;
             const { root, ids } = familyOf(store, taskId);
-            // A completed or cancelled task never repaints as back with them.
             if (store.getTask(root) === null || familyEnded(store, ids, null))
                 continue;
             const source = cardSource(store, root);
             if (source === null)
                 continue;
-            // The owner's lead let it go: only its owner's card hears of it (store.pingAllowed).
             if (withActor({ account: owner, lead: true }, () => store.enqueueNotification({ dedupeKey: `lead-lapsed:${root}:${owner}:${claim.lastActedAt}`,
                 kind: LEAD_LAPSED_KIND, subject: leadLapsed(leadNameOf(store, owner)), body: "", link: chatControlHref("task", root), source }, now)))
                 count++;
         }
     }
     catch {
-        // An older store being read by a newer build: nothing to repaint.
     }
     return count;
 }
-/** The lead's act on a task that a claim counts (a retry, a state change, a steer): one ledger row as the lead. */
 export function noteLeadWork(store, actor, taskId, what, now) {
     if (!actor.lead)
         return;
@@ -253,8 +203,6 @@ const ACT_WORDS = {
     "task filed": "filed", "task approved": "approved", "task cancelled": "cancelled", "task completed": "completed",
     "task handed to a person": "handed on", [LEAD_CLAIMED]: "working on",
 };
-/** What `owner`'s own lead is doing now and when it last acted, both from its one newest act: its words when that
- * was a say, else the act in words. Nobody (null) has no lead line: another person's lead is never theirs. */
 export function leadActivity(store, owner) {
     if (owner == null || owner === "")
         return null;
@@ -277,7 +225,6 @@ export function leadActivity(store, owner) {
         return null;
     }
 }
-/** "just now", "3 min ago", "2 h ago", "yesterday", "4 days ago". */
 export function agoWords(at, now) {
     const minutes = Math.max(0, Math.floor((now.getTime() - Date.parse(at)) / 60_000));
     if (!Number.isFinite(minutes) || minutes < 1)
@@ -290,7 +237,6 @@ export function agoWords(at, now) {
     const days = Math.floor(hours / 24);
     return days === 1 ? "yesterday" : `${days} days ago`;
 }
-/** The one line `toolroll status` and the console say: "Lead: fixing 0.9.12's release check · 3 min ago". */
 export function leadActivityLine(activity, now) {
     return `${activity.name}: ${activity.doing} · ${agoWords(activity.at, now)}`;
 }