toolroll 0.9.97 → 0.9.98

package/dist/typed-start.d.ts

@@ -0,0 +1,51 @@
+import type { Store } from "./store.js";
+/** The card's last line on Telegram, outside the terms (terms are digest-bound), in Toolroll's fixed words. */
+export declare const TYPED_START_LINE = "Tap Start work, or reply yes.";
+/** What a yes that counted for nothing says. It is never passed to the lead. */
+export declare const TYPED_START_REFUSED = "That yes didn't start anything. Tap Start work on the card.";
+/** Whether a typed message is exactly one of the fixed yes words: trimmed, lower-cased, one trailing `.` or `!` removed.
+ * Anything longer or different ("yes but make it blue", "ok", "sure") is an ordinary message to the lead. */
+export declare function typedYes(text: string): boolean;
+export type TypedStartCard = {
+    proposal: number;
+    cardMessage: string;
+    stamp: string;
+    how: "reply" | "next";
+};
+/**
+ * The Start card a yes in this chat answers, by ids, or null. Every condition from the plan:
+ * - the chat's last sent card is a card for a `task_start` proposal: sent (a confirmed message id), never
+ *   uncertain, the last part of its event, sent with its buttons and the fixed "reply yes" line, its terms whole on the
+ *   card (sharedActionAllowsChallenge);
+ * - the message is a Telegram reply to that card's message (`reply`), or replies to nothing and its message id is the
+ *   card's plus one (`next`): nothing at all was sent or typed in the chat between them;
+ * - the proposal is pending, the only pending proposal in the person's own thread with the lead (never a team room),
+ *   drafted in a turn that answered (one finalized after a timeout doesn't qualify).
+ */
+export declare function typedStartCard(store: Store, chat: {
+    binding: number;
+    chatId: string;
+    approver: string;
+}, message: {
+    id: string;
+    replyTo: string | null;
+}): TypedStartCard | null;
+/** Record a typed yes for the message just saved (event `m<update_id>`), in the caller's transaction. */
+export declare function recordTypedStart(store: Store, event: string, card: TypedStartCard, now: Date): void;
+export type TypedStartRow = {
+    provider: "telegram";
+    event: string;
+    proposal: number;
+    cardMessage: string;
+    stamp: string;
+    how: "reply" | "next";
+    outcome: "started" | "refused" | "not-counted" | null;
+    taskId: string | null;
+};
+/** A message's typed-yes record, or null when it has none. */
+export declare function typedStartOf(store: Store, provider: "telegram", event: string): TypedStartRow | null;
+/** Whether an UNSETTLED typed yes names exactly this proposal: the only thing `typedStart` may open, and only once. */
+export declare function typedStartNames(store: Store, typed: {
+    provider: string;
+    event: string;
+}, proposal: number): boolean;

package/dist/typed-start.js

@@ -0,0 +1,98 @@
+/**
+ * A typed yes to a Start card, on Telegram (docs/plans/one-step-chat.md C5). Toolroll reads the word when the message
+ * arrives, before any model runs: the lead never sees it as an instruction and has no tool that presses a card. Which
+ * card a yes belongs to comes from Telegram's own message ids and Toolroll's delivery record (chat_part), never from the
+ * text or the lead.
+ *
+ * Read at ingress (telegram.ts applyConversation, the typed-message path only) in the transaction that saves the message,
+ * and read again from the tables by confirmTypedStart (lead-doors.ts) in the transaction that acts on it.
+ */
+import { sharedActionAllowsChallenge, sharedActionPayload } from "./chat-actions.js";
+/** The card's last line on Telegram, outside the terms (terms are digest-bound), in Toolroll's fixed words. */
+export const TYPED_START_LINE = "Tap Start work, or reply yes.";
+/** What a yes that counted for nothing says. It is never passed to the lead. */
+export const TYPED_START_REFUSED = "That yes didn't start anything. Tap Start work on the card.";
+const WORDS = new Set(["yes", "y", "yep", "yeah", "yes please", "yes start", "start", "start it", "go ahead", "do it"]);
+/** Whether a typed message is exactly one of the fixed yes words: trimmed, lower-cased, one trailing `.` or `!` removed.
+ * Anything longer or different ("yes but make it blue", "ok", "sure") is an ordinary message to the lead. */
+export function typedYes(text) {
+    const word = text.trim().toLowerCase().replace(/[.!]$/, "");
+    return WORDS.has(word);
+}
+/**
+ * The Start card a yes in this chat answers, by ids, or null. Every condition from the plan:
+ * - the chat's last sent card is a card for a `task_start` proposal: sent (a confirmed message id), never
+ *   uncertain, the last part of its event, sent with its buttons and the fixed "reply yes" line, its terms whole on the
+ *   card (sharedActionAllowsChallenge);
+ * - the message is a Telegram reply to that card's message (`reply`), or replies to nothing and its message id is the
+ *   card's plus one (`next`): nothing at all was sent or typed in the chat between them;
+ * - the proposal is pending, the only pending proposal in the person's own thread with the lead (never a team room),
+ *   drafted in a turn that answered (one finalized after a timeout doesn't qualify).
+ */
+export function typedStartCard(store, chat, message) {
+    const own = /^[1-9][0-9]{0,15}$/;
+    if (!own.test(message.id) || (message.replyTo !== null && !own.test(message.replyTo)))
+        return null;
+    // The chat's last sent card, by Telegram's own message id (ids in one private chat run in order, both directions).
+    const last = store.handle.prepare(`SELECT p.id, p.event, p.ordinal, p.payload, p.message, p.uncertain FROM chat_part p
+      JOIN chat_event e ON e.provider = p.provider AND e.id = p.event
+     WHERE p.provider = 'telegram' AND e.binding = ? AND e.channel = ? AND p.state = 'sent' AND p.message IS NOT NULL
+       AND json_valid(p.payload) AND json_extract(p.payload, '$.card') = 1
+     ORDER BY CAST(p.message AS INTEGER) DESC LIMIT 1`).get(chat.binding, chat.chatId);
+    if (last === undefined)
+        return null;
+    const cardMessage = String(last["message"]);
+    if (!own.test(cardMessage) || Number(last["uncertain"]) !== 0)
+        return null;
+    const how = message.replyTo === cardMessage ? "reply" : message.replyTo === null && BigInt(message.id) === BigInt(cardMessage) + 1n ? "next" : null;
+    if (how === null)
+        return null;
+    const lastOrdinal = store.handle.prepare("SELECT MAX(ordinal) AS n FROM chat_part WHERE provider = 'telegram' AND event = ?").get(String(last["event"]))?.["n"];
+    if (Number(lastOrdinal) !== Number(last["ordinal"]))
+        return null;
+    let content;
+    try {
+        content = JSON.parse(String(last["payload"]));
+    }
+    catch {
+        return null;
+    }
+    if (content.card !== true || typeof content.proposal !== "number" || !Array.isArray(content.keyboard) || typeof content.text !== "string" || !content.text.trimEnd().endsWith(TYPED_START_LINE))
+        return null;
+    const proposal = store.getLeadProposal(content.proposal);
+    const action = proposal?.kind === "action" ? sharedActionPayload(proposal.payload) : null;
+    if (proposal === null || action === null || action.operation !== "task_start" || !sharedActionAllowsChallenge(action, "telegram") || proposal.state !== "pending")
+        return null;
+    const thread = store.getLeadThread(proposal.thread);
+    if (thread === null || thread.approver !== chat.approver || thread.closedAt !== null)
+        return null;
+    if (store.handle.prepare("SELECT 1 AS hit FROM team_conversation WHERE thread = ?").get(proposal.thread) !== undefined)
+        return null;
+    if (store.getLeadTurn(proposal.turn)?.state !== "answered")
+        return null;
+    const pending = Number(store.handle.prepare("SELECT COUNT(*) AS n FROM lead_proposal WHERE thread = ? AND state = 'pending'").get(proposal.thread)?.["n"]);
+    if (pending !== 1)
+        return null;
+    return { proposal: proposal.id, cardMessage, stamp: action.stamp, how };
+}
+/** Record a typed yes for the message just saved (event `m<update_id>`), in the caller's transaction. */
+export function recordTypedStart(store, event, card, now) {
+    store.handle.prepare(`INSERT INTO chat_typed_start (provider, event, proposal, card_message, stamp, how, created) VALUES ('telegram', ?, ?, ?, ?, ?, ?)`)
+        .run(event, card.proposal, card.cardMessage, card.stamp, card.how, now.toISOString());
+}
+/** A message's typed-yes record, or null when it has none. */
+export function typedStartOf(store, provider, event) {
+    const row = store.handle.prepare("SELECT * FROM chat_typed_start WHERE provider = ? AND event = ?").get(provider, event);
+    if (row === undefined)
+        return null;
+    return { provider, event, proposal: Number(row["proposal"]), cardMessage: String(row["card_message"]), stamp: String(row["stamp"]), how: row["how"] === "reply" ? "reply" : "next",
+        outcome: row["outcome"] === "started" || row["outcome"] === "refused" || row["outcome"] === "not-counted" ? row["outcome"] : null,
+        taskId: row["task_id"] === null ? null : String(row["task_id"]) };
+}
+/** Whether an UNSETTLED typed yes names exactly this proposal: the only thing `typedStart` may open, and only once. */
+export function typedStartNames(store, typed, proposal) {
+    if (typed.provider !== "telegram" || typeof typed.event !== "string")
+        return false;
+    const row = typedStartOf(store, "telegram", typed.event);
+    return row !== null && row.outcome === null && row.proposal === proposal;
+}

package/dist/wake-hub.d.ts

@@ -0,0 +1,72 @@
+/**
+ * One shared wake poller per process (docs/plans/live-wakeups.md, slice 3).
+ *
+ * Every dispatch loop and build lane used to doze by reading `wakeSeq()` from SQLite every 50 ms on its own, so a
+ * service with twelve projects and eight lanes made hundreds of reads a second while idle. The hub keeps ONE timer
+ * per store: it runs only while something waits, reads the counter once per beat, and resolves each waiter whose
+ * baseline the counter has passed.
+ *
+ * - A waiter resolves with why: "wake" (the counter moved past its baseline), "deadline" (its time came), or "poke"
+ *   (its `until` became true, or someone poked it directly: a stop, a lost lease, a recovered reconciliation).
+ * - No lost wakeup. The counter only ever moves forward, so a bump that lands after the caller read its baseline and
+ *   before it registered is seen on the very next read. Registration is synchronous; nothing yields in between.
+ * - Every waiter is checked on every beat (50 ms, well inside the one-second floor the plan asks for), including its
+ *   `until`, which must be cheap and in-memory: it never reads the database.
+ * - The hub only gives promptness, never permission: claim and spawn fences re-prove everything after a wake.
+ * - Nothing here watches files or listens to commits. The timer is cleared as soon as nobody waits, so a stopped
+ *   worker (or a finished test) keeps no timer alive.
+ */
+export type WakeWhy = "wake" | "deadline" | "poke";
+/** Something a caller can poke to end the waits registered with it, now (a stop, a lost lease, a recovery). */
+export declare class WakePoker {
+    private readonly listeners;
+    poke(): void;
+    /** @internal */
+    listen(listener: () => void): () => void;
+}
+export type WakeWaiter = {
+    /** The counter value the caller last acted on. Any later value wakes it. */
+    baseline: number;
+    /** Epoch milliseconds: resolve with "deadline" once the clock reaches it. */
+    deadline: number;
+    /** A cheap, in-memory condition checked every beat (never a database read); true resolves with "poke". */
+    until?: () => boolean;
+    /** Pokes on this end the wait at once with "poke". */
+    poker?: WakePoker;
+};
+export type WakeHubOptions = {
+    /** How often the one timer reads the counter while something waits. */
+    intervalMs?: number;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+};
+export declare const WAKE_HUB_INTERVAL_MS = 50;
+export declare class WakeHub {
+    private readonly read;
+    private readonly waiters;
+    private timer;
+    private readonly intervalMs;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readsMade;
+    constructor(read: () => number, options?: WakeHubOptions);
+    /** Wait until the counter passes `baseline`, the deadline comes, or the waiter is poked. */
+    changed(waiter: WakeWaiter): Promise<WakeWhy>;
+    /** End every wait in this process now (the service's stop signal). */
+    poke(): void;
+    /** How many waits are open (tests and diagnostics). */
+    waiting(): number;
+    /** Whether the beat timer is running (tests). */
+    running(): boolean;
+    /** How many counter reads the hub has made (tests: one per beat, whatever the number of waiters). */
+    reads(): number;
+    private arm;
+    private idleIfEmpty;
+    private beat;
+}
+/** The one hub for this store (one per process under `up`, which shares a store across project loops). */
+export declare function wakeHubFor(store: {
+    wakeSeq(): number;
+}): WakeHub;

package/dist/wake-hub.js

@@ -0,0 +1,151 @@
+/**
+ * One shared wake poller per process (docs/plans/live-wakeups.md, slice 3).
+ *
+ * Every dispatch loop and build lane used to doze by reading `wakeSeq()` from SQLite every 50 ms on its own, so a
+ * service with twelve projects and eight lanes made hundreds of reads a second while idle. The hub keeps ONE timer
+ * per store: it runs only while something waits, reads the counter once per beat, and resolves each waiter whose
+ * baseline the counter has passed.
+ *
+ * - A waiter resolves with why: "wake" (the counter moved past its baseline), "deadline" (its time came), or "poke"
+ *   (its `until` became true, or someone poked it directly: a stop, a lost lease, a recovered reconciliation).
+ * - No lost wakeup. The counter only ever moves forward, so a bump that lands after the caller read its baseline and
+ *   before it registered is seen on the very next read. Registration is synchronous; nothing yields in between.
+ * - Every waiter is checked on every beat (50 ms, well inside the one-second floor the plan asks for), including its
+ *   `until`, which must be cheap and in-memory: it never reads the database.
+ * - The hub only gives promptness, never permission: claim and spawn fences re-prove everything after a wake.
+ * - Nothing here watches files or listens to commits. The timer is cleared as soon as nobody waits, so a stopped
+ *   worker (or a finished test) keeps no timer alive.
+ */
+/** Something a caller can poke to end the waits registered with it, now (a stop, a lost lease, a recovery). */
+export class WakePoker {
+    listeners = new Set();
+    poke() {
+        for (const listener of [...this.listeners])
+            listener();
+    }
+    /** @internal */
+    listen(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+}
+export const WAKE_HUB_INTERVAL_MS = 50;
+export class WakeHub {
+    read;
+    waiters = new Set();
+    timer = null;
+    intervalMs;
+    now;
+    setTimer;
+    clearTimer;
+    readsMade = 0;
+    constructor(read, options = {}) {
+        this.read = read;
+        this.intervalMs = options.intervalMs ?? WAKE_HUB_INTERVAL_MS;
+        this.now = options.now ?? Date.now;
+        this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = options.clearTimer ?? (handle => clearTimeout(handle));
+    }
+    /** Wait until the counter passes `baseline`, the deadline comes, or the waiter is poked. */
+    changed(waiter) {
+        return new Promise((resolve, reject) => {
+            let unlisten = () => { };
+            const entry = {
+                ...waiter,
+                settle: why => {
+                    if (!this.waiters.delete(entry))
+                        return;
+                    unlisten();
+                    this.idleIfEmpty();
+                    resolve(why);
+                },
+                fail: error => {
+                    if (!this.waiters.delete(entry))
+                        return;
+                    unlisten();
+                    this.idleIfEmpty();
+                    reject(error);
+                },
+            };
+            this.waiters.add(entry);
+            if (waiter.poker !== undefined)
+                unlisten = waiter.poker.listen(() => entry.settle("poke"));
+            // Already true (a stop that landed before the wait, a deadline in the past): no beat needed.
+            if (waiter.until?.() === true) {
+                entry.settle("poke");
+                return;
+            }
+            if (this.now() >= waiter.deadline) {
+                entry.settle("deadline");
+                return;
+            }
+            this.arm();
+        });
+    }
+    /** End every wait in this process now (the service's stop signal). */
+    poke() {
+        for (const entry of [...this.waiters])
+            entry.settle("poke");
+    }
+    /** How many waits are open (tests and diagnostics). */
+    waiting() { return this.waiters.size; }
+    /** Whether the beat timer is running (tests). */
+    running() { return this.timer !== null; }
+    /** How many counter reads the hub has made (tests: one per beat, whatever the number of waiters). */
+    reads() { return this.readsMade; }
+    arm() {
+        if (this.timer !== null || this.waiters.size === 0)
+            return;
+        this.timer = this.setTimer(() => this.beat(), this.intervalMs);
+    }
+    idleIfEmpty() {
+        if (this.waiters.size > 0 || this.timer === null)
+            return;
+        this.clearTimer(this.timer);
+        this.timer = null;
+    }
+    beat() {
+        this.timer = null;
+        if (this.waiters.size === 0)
+            return;
+        let seq;
+        try {
+            this.readsMade++;
+            seq = this.read();
+        }
+        catch (error) {
+            // A read that fails reaches every waiter, as the loops' own read used to: nothing is silently swallowed.
+            for (const entry of [...this.waiters])
+                entry.fail(error);
+            return;
+        }
+        const now = this.now();
+        for (const entry of [...this.waiters]) {
+            let stop = false;
+            try {
+                stop = entry.until?.() === true;
+            }
+            catch (error) {
+                entry.fail(error);
+                continue;
+            }
+            if (stop)
+                entry.settle("poke");
+            else if (seq !== entry.baseline)
+                entry.settle("wake");
+            else if (now >= entry.deadline)
+                entry.settle("deadline");
+        }
+        this.arm();
+    }
+}
+const hubs = new WeakMap();
+/** The one hub for this store (one per process under `up`, which shares a store across project loops). */
+export function wakeHubFor(store) {
+    let hub = hubs.get(store);
+    if (hub === undefined) {
+        hub = new WakeHub(() => store.wakeSeq());
+        hubs.set(store, hub);
+    }
+    return hub;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.97",
+  "version": "0.9.98",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"