toolroll 0.5.0

package/dist/teams.js

@@ -0,0 +1,124 @@
+/** Microsoft Teams: the leased delivery loop hosted by the ordinary worker,
+ * and the HTTPS receiver the console mounts for the Bot Framework. Teams
+ * has no client-initiated socket, so inbound activities arrive over HTTPS
+ * and everything else runs from the database like the other channels. */
+import { randomBytes } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+import { ChatState } from "./chat-delivery-state.js";
+import { chatObject as object } from "./chat-delivery.js";
+import { loadTeamsCredentials, teamsAccessToken, teamsApi, verifyTeamsToken, TeamsError } from "./teams-api.js";
+import { deliverTeamsPart, planTeamsNotifications, planTeamsRooms, processTeamsEvent, receiveTeams } from "./teams-chat.js";
+export const TEAMS_ACTIVITY_BYTES = 64 * 1024;
+export const TEAMS_MESSAGES_PATH = "/teams/messages";
+/** The receiver: prove the Bot Framework token for this app, save the activity, acknowledge. Nothing runs here. */
+export async function handleTeamsHttp(request, response, options) {
+    const url = new URL(request.url ?? "/", "http://standing-orders.local");
+    if (url.pathname !== TEAMS_MESSAGES_PATH)
+        return false;
+    const reply = (status, body = "{}") => { response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }); response.end(body); request.resume(); return true; };
+    if (request.method !== "POST")
+        return reply(405);
+    const credentials = loadTeamsCredentials(options.dir);
+    if (credentials === null)
+        return reply(404);
+    const claims = await verifyTeamsToken(request.headers.authorization, credentials.app, options.fetcher ?? fetch);
+    if (claims === null)
+        return reply(401);
+    if (Number(request.headers["content-length"] ?? 0) > TEAMS_ACTIVITY_BYTES)
+        return reply(413);
+    let raw = "";
+    try {
+        await new Promise((resolve, reject) => {
+            request.setEncoding("utf8");
+            request.on("data", (chunk) => { raw += chunk; if (raw.length > TEAMS_ACTIVITY_BYTES)
+                reject(new Error("too-large")); });
+            request.on("end", resolve);
+            request.on("error", reject);
+        });
+    }
+    catch (error) {
+        return reply(error instanceof Error && error.message === "too-large" ? 413 : 400);
+    }
+    let activity;
+    try {
+        activity = JSON.parse(raw);
+    }
+    catch {
+        return reply(400);
+    }
+    const state = new ChatState(options.store, "teams");
+    try {
+        receiveTeams(state, credentials, activity, claims.serviceUrl, options.clock?.() ?? new Date());
+    }
+    catch {
+        return reply(500, JSON.stringify({ error: "not saved" }));
+    }
+    // Teams expects 200 for a handled activity; an unhandled shape is also 200,
+    // so that a stranger learns nothing from the answer.
+    return reply(200);
+}
+/** The worker-side loop: a lease per installation, one pass a second. */
+export async function followTeams(options) {
+    const owner = randomBytes(16).toString("hex"), state = new ChatState(options.store, "teams");
+    const pause = async (ms) => { try {
+        await sleep(ms, undefined, { signal: options.signal });
+    }
+    catch { /* shutdown */ } };
+    while (!options.signal.aborted) {
+        const credentials = loadTeamsCredentials(options.dir);
+        if (!credentials || !state.lease(credentials.installation, owner, new Date())) {
+            await pause(2000);
+            continue;
+        }
+        let alive = true;
+        const same = () => {
+            const current = loadTeamsCredentials(options.dir);
+            return alive && !options.signal.aborted && current?.installation === credentials.installation && current.secret === credentials.secret && state.owns(credentials.installation, owner);
+        };
+        const problem = (message) => state.prepare("UPDATE chat_runtime SET problem=? WHERE installation=? AND owner=?").run(message, credentials.installation, owner);
+        const stop = () => { alive = false; };
+        options.signal.addEventListener("abort", stop, { once: true });
+        const heartbeat = setInterval(() => { if (!same() || !state.lease(credentials.installation, owner, new Date()))
+            stop(); }, 10_000);
+        const chat = { ...options, identity: credentials, owner, api: teamsApi(credentials, options.fetcher), canNotify: options.notifications, current: same };
+        try {
+            // Connected means the app can sign in; inbound reachability is the operator's endpoint to verify.
+            try {
+                await teamsAccessToken(credentials, options.fetcher);
+                state.prepare("UPDATE chat_runtime SET connected=?,problem=NULL WHERE installation=? AND owner=?").run(new Date().toISOString(), credentials.installation, owner);
+            }
+            catch (error) {
+                problem(error instanceof TeamsError ? error.message : "Microsoft sign-in failed. Check the Teams app credentials.");
+                await pause(30_000);
+                continue;
+            }
+            while (same()) {
+                const retry = state.prepare("SELECT retry_at FROM chat_runtime WHERE installation=?").get(credentials.installation)?.retry_at;
+                if (typeof retry === "string" && retry > new Date().toISOString()) {
+                    await pause(1000);
+                    continue;
+                }
+                await processTeamsEvent(chat);
+                if (same())
+                    await planTeamsRooms(chat);
+                if (same())
+                    await deliverTeamsPart(chat);
+                if (same() && options.notifications())
+                    await planTeamsNotifications(chat);
+                await pause(1000);
+            }
+        }
+        catch {
+            if (alive)
+                problem("Teams delivery is unavailable. Retrying shortly.");
+        }
+        finally {
+            clearInterval(heartbeat);
+            alive = false;
+            options.signal.removeEventListener("abort", stop);
+            state.prepare("UPDATE chat_runtime SET owner=NULL,lease_until=NULL,connected=NULL WHERE installation=? AND owner=?").run(credentials.installation, owner);
+        }
+        await pause(5000);
+    }
+}
+export { object };

package/dist/telegram-flow.d.ts

@@ -0,0 +1,49 @@
+import { type FlowStage } from "./flows.js";
+import type { InlineButton } from "./telegram-mate.js";
+import type { FlowCardRow, FlowRow, Store, TelegramBinding, TelegramFlowAction, TelegramFlowPrompt } from "./store.js";
+export declare const FLOW_DECIDE_KEY: RegExp;
+type Waiting = {
+    card: FlowCardRow;
+    flow: FlowRow;
+    stage: FlowStage;
+    draft: FlowStage | null;
+};
+/** The card, if it is still at that visit, waiting at a decision. */
+export declare function flowDecisionAt(store: Store, cardId: number, entry: number): Waiting | null;
+/** Buttons for one visit, minted before the send; `place` stamps the message they landed on. */
+export declare function flowButtons(store: Store, binding: TelegramBinding, waiting: Waiting, now: Date): {
+    keyboard: InlineButton[][];
+    tokens: string[];
+};
+export type FlowTapEffect = {
+    kind: "ack";
+    text: string;
+} | {
+    kind: "edit";
+    text: string;
+} | {
+    kind: "prompt";
+    text: string;
+    placeholder: string;
+    prompt: Omit<TelegramFlowPrompt, "messageId">;
+};
+/** A tapped flow button, applied inside the update's transaction. */
+export declare function applyFlowTap(store: Store, binding: TelegramBinding, action: TelegramFlowAction, message: {
+    chatId: string;
+    messageId: string;
+    text: string;
+}, repos: readonly string[] | null, now: Date): FlowTapEffect[];
+export type FlowReplyEffect = {
+    kind: "say";
+    text: string;
+}
+/** The edited draft, back for a decision: send it with these buttons, then place them. */
+ | {
+    kind: "decide";
+    text: string;
+    keyboard: InlineButton[][];
+    tokens: string[];
+};
+/** A reply to an Edit or Send back prompt, applied inside the update's transaction. */
+export declare function applyFlowReply(store: Store, binding: TelegramBinding, prompt: TelegramFlowPrompt, text: string, repos: readonly string[] | null, now: Date): FlowReplyEffect[];
+export {};

package/dist/telegram-flow.js

@@ -0,0 +1,110 @@
+/**
+ * Flow decisions on Telegram (v86). A card waiting at a "Person decides"
+ * zone reaches the decider with the draft in front of it (when a Draft zone
+ * sends it there) and three buttons: Approve, Edit, Send back.
+ *
+ * - Approve decides it through the same door as the console
+ *   (decideFlowCard), as the paired person, for exactly the visit the
+ *   message was about.
+ * - Edit asks for the person's own version as a reply; it replaces the
+ *   draft on the card and comes back with fresh buttons, so what is
+ *   approved is always what they read.
+ * - Send back asks what should change; the reply is the note.
+ *
+ * Every button is one opaque token for one visit of one card, placed on the
+ * message it rides. A card that moved on answers so; a tap from anyone but
+ * the paired person and chat never reaches here (telegram.ts checks it).
+ */
+import { randomBytes } from "node:crypto";
+import { keptDraft } from "./flow-draft.js";
+import { decideFlowCard, draftFor, flowDefinitionOf } from "./flow-engine.js";
+import { deciderOf } from "./flows.js";
+export const FLOW_DECIDE_KEY = /^flow-decide:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})$/;
+const DRAFT_LIMIT = 4000;
+/** The card, if it is still at that visit, waiting at a decision. */
+export function flowDecisionAt(store, cardId, entry) {
+    const card = store.getFlowCard(cardId);
+    const flow = card === null ? null : store.getFlow(card.flow);
+    const definition = flow === null ? null : flowDefinitionOf(flow);
+    if (card === null || flow === null || definition === null || card.state !== "active" || card.entry !== entry)
+        return null;
+    const stage = definition.stages.find(one => one.id === card.stage);
+    if (stage === undefined || stage.kind !== "approval")
+        return null;
+    return { card, flow, stage, draft: draftFor(definition, stage) };
+}
+/** Buttons for one visit, minted before the send; `place` stamps the message they landed on. */
+export function flowButtons(store, binding, waiting, now) {
+    const mint = (action) => ({ action, token: randomBytes(16).toString("hex") });
+    const approve = mint("approve");
+    const edit = waiting.draft !== null && waiting.card.outputs[waiting.draft.id] !== undefined ? mint("edit") : null;
+    const back = waiting.stage.onFail !== null ? mint("send-back") : null;
+    const all = [approve, edit, back].filter((one) => one !== null);
+    store.createTelegramFlowActions({ binding: binding.id, chatId: binding.chatId, card: waiting.card.id, entry: waiting.card.entry }, all, now);
+    const second = [edit === null ? null : { text: "✏️ Edit", callback_data: edit.token }, back === null ? null : { text: "↩️ Send back", callback_data: back.token }]
+        .filter((one) => one !== null);
+    return { keyboard: [[{ text: "✅ Approve", callback_data: approve.token }], ...(second.length === 0 ? [] : [second])], tokens: all.map(one => one.token) };
+}
+/** A tapped flow button, applied inside the update's transaction. */
+export function applyFlowTap(store, binding, action, message, repos, now) {
+    if (action.consumedAt !== null || action.expiresAt <= now.toISOString())
+        return [{ kind: "ack", text: "That was already decided, or these buttons are too old." }];
+    const waiting = flowDecisionAt(store, action.card, action.entry);
+    if (waiting === null)
+        return [{ kind: "ack", text: "That card has moved on since; nothing was changed." }];
+    const decider = deciderOf(waiting.stage, waiting.flow);
+    if (decider !== null && decider !== binding.approver)
+        return [{ kind: "ack", text: `Only ${decider} decides here.` }];
+    if (action.action === "approve") {
+        if (repos === null)
+            return [{ kind: "ack", text: "Couldn't check your projects just now. Try again in a moment." }];
+        const decided = decideFlowCard(store, { card: waiting.card.id, decision: "approve", note: null, actor: binding.approver, repos, entry: action.entry }, now);
+        if (!decided.ok)
+            return [{ kind: "ack", text: decided.message.slice(0, 190) }];
+        store.retireTelegramFlowVisit(action.card, action.entry, now);
+        return [{ kind: "ack", text: "Approved" }, { kind: "edit", text: `${message.text}\n\n✅ You approved it. ${decided.said}`.slice(0, 4000) }];
+    }
+    const prompt = { chatId: binding.chatId, binding: binding.id, card: action.card, entry: action.entry, mode: action.action };
+    if (action.action === "edit") {
+        return [{ kind: "ack", text: "Send your version" }, { kind: "prompt", prompt, placeholder: "Your version of the draft",
+                text: `Send your version of the draft for “${waiting.card.title}” as a reply to this message. It replaces the draft, and comes back here for you to approve.` }];
+    }
+    const back = waiting.stage.onFail === null ? "the zone before" : titleOf(waiting, waiting.stage.onFail);
+    return [{ kind: "ack", text: "What should change?" }, { kind: "prompt", prompt, placeholder: "What should change",
+            text: `What should change on “${waiting.card.title}”? Reply to this message and it goes back to ${back} with your note.` }];
+}
+const titleOf = (waiting, id) => flowDefinitionOf(waiting.flow)?.stages.find(one => one.id === id)?.title ?? id;
+/** A reply to an Edit or Send back prompt, applied inside the update's transaction. */
+export function applyFlowReply(store, binding, prompt, text, repos, now) {
+    if (prompt.binding !== binding.id)
+        return [];
+    const waiting = flowDecisionAt(store, prompt.card, prompt.entry);
+    if (waiting === null) {
+        store.retireTelegramFlowVisit(prompt.card, prompt.entry, now);
+        return [{ kind: "say", text: "That card has moved on since; nothing was changed." }];
+    }
+    const said = text.trim();
+    if (said === "")
+        return [{ kind: "say", text: prompt.mode === "edit" ? "Send the text itself as a reply." : "Say what should change." }];
+    if (prompt.mode === "edit") {
+        if (waiting.draft === null)
+            return [{ kind: "say", text: "This decision has no draft to edit." }];
+        if (said.length > DRAFT_LIMIT)
+            return [{ kind: "say", text: `Keep it under ${DRAFT_LIMIT} characters.` }];
+        const kept = keptDraft(said);
+        store.updateFlowCard(waiting.card.id, { outputs: { ...waiting.card.outputs, [waiting.draft.id]: kept } }, now);
+        store.addFlowComment({ card: waiting.card.id, author: binding.approver, body: "Edited the draft in Telegram.", mentions: [] }, now);
+        store.retireTelegramFlowVisit(prompt.card, prompt.entry, now);
+        const fresh = flowDecisionAt(store, prompt.card, prompt.entry);
+        const buttons = flowButtons(store, binding, fresh, now);
+        return [{ kind: "decide", keyboard: buttons.keyboard, tokens: buttons.tokens,
+                text: `${waiting.flow.name}: your version of the draft for “${waiting.card.title}”\n\n${kept}\n\nApprove to send it as written.` }];
+    }
+    if (repos === null)
+        return [{ kind: "say", text: "Couldn't check your projects just now. Reply again in a moment." }];
+    const decided = decideFlowCard(store, { card: waiting.card.id, decision: "send-back", note: said.slice(0, 2000), actor: binding.approver, repos, entry: prompt.entry }, now);
+    if (!decided.ok)
+        return [{ kind: "say", text: decided.message }];
+    store.retireTelegramFlowVisit(prompt.card, prompt.entry, now);
+    return [{ kind: "say", text: `↩️ ${decided.said}` }];
+}

package/dist/telegram-mate.d.ts

@@ -0,0 +1,137 @@
+import { type PhoneLink } from "./chat-channel.js";
+export { channelRepos as telegramConversationRepos, resolveChannelMate as resolveTelegramMate, tooLongText, whichTaskText, replyContextFor, NO_PHONE_LINK, NO_TASK_LINK, proposalLink, confirmedLink, proposalPreview, proposalOutcomeText, handoffCardText, confirmedCardText, CHAT_ACTION_PARITY as TELEGRAM_ACTION_PARITY, parityGaps, type PhoneLink, type ResolvedMate, type ParitySupport } from "./chat-channel.js";
+import { type DoorOptions } from "./mate-doors.js";
+import type { Store, TelegramBinding } from "./store.js";
+import type { SubscriptionMateRunner } from "./subscription-chat.js";
+import type { TelegramTransport } from "./telegram.js";
+/** How long one claimed turn may go without a heartbeat before another poller may take it over. */
+export declare const CONVERSATION_CLAIM_MS: number;
+/** A busy engine (one turn at a time) defers a queued message this long, up to the age bound below. */
+export declare const CONVERSATION_RETRY_MS = 5000;
+export declare const CONVERSATION_MAX_AGE_MS: number;
+/** A card's buttons and an armed irreversible challenge live this long. */
+export declare const CARD_TTL_MS: number;
+export declare const CHALLENGE_TTL_MS: number;
+export type TelegramConversationOptions = {
+    /** Where evidence lives — the same root the console and CLI read results from. */
+    evidenceRoot: string;
+    /** Injected by tests; production invokes the isolated local harness. */
+    subscriptionRunner?: SubscriptionMateRunner;
+    /** The held-session supervisor in this process, when there is one (a stop fences through it). */
+    held?: DoorOptions["held"];
+    /**
+     * The https origin a phone link may open, read again on EVERY call (a
+     * card is linked immediately before it is sent or edited, never from a
+     * stored URL), or null when no trusted origin is configured. Production
+     * wires `phoneOrigin` from webhooks.ts; absent, no card carries a link.
+     */
+    phoneOrigin?: () => string | null;
+};
+/** One Bot API call, the shape telegram.ts injects. */
+export type Transport = TelegramTransport;
+/**
+ * The phone's project ceiling: the enrolled registry, canonicalized and
+ * deduplicated IN ORDER exactly as the console's managed list is, then
+ * narrowed to what this approver's account may access. Order matters —
+ * `r1..rN` is an index and the ceiling digest hashes the order — so a
+ * console session over the same enrollment shares its digest here.
+ */
+/** The engine's request identity for one inbound message: exact bot, binding and update, never text. */
+export declare function telegramRequestId(botId: string, bindingId: number, updateId: number): string;
+/** The one channel problem that is transient: the registry could not be read now. Retried, never a refusal. */
+export declare const UNREADABLE_REGISTRY = "current project access could not be read";
+/**
+ * Is the channel still what a turn opened under? The live binding must be
+ * the SAME row and generation, its approver still an approver, and the
+ * enrolled ceiling (reloaded now) still the exact list the principal
+ * holds — or, for a reply recovered after a restart, the ceiling digest
+ * its session was minted under. A string names what changed; null means
+ * nothing did.
+ */
+export declare function telegramChannelProblem(store: Store, expected: {
+    botId: string;
+    bindingId: number;
+    approverGeneration: number;
+} & ({
+    repos: readonly string[];
+} | {
+    ceilingDigest: string;
+}), readProjects: () => Promise<readonly string[]>): Promise<string | null>;
+export declare function phoneLinkButton(origin: string | null, link: PhoneLink | null): InlineButton[] | null;
+/** One inline button: an opaque callback token (a real in-chat act) or a url (navigation, never authority). */
+export type InlineButton = {
+    text: string;
+    callback_data: string;
+} | {
+    text: string;
+    url: string;
+};
+type Keyboard = InlineButton[][];
+/** What a part persists: callback tokens only. A url is minted at send time, never stored. */
+type CallbackKeyboard = {
+    text: string;
+    callback_data: string;
+}[][];
+/** Mint the card's tokens before the send, so a tap can never name a token that does not exist. */
+export declare function mintCardTokens(store: Store, binding: TelegramBinding, proposal: number, now: Date, messageId?: string, chatId?: string): {
+    keyboard: CallbackKeyboard;
+    tokens: string[];
+};
+export type CardEffect = {
+    kind: "ack";
+    text: string;
+} | {
+    kind: "edit";
+    text: string;
+    keyboard?: Keyboard;
+} | {
+    kind: "signal";
+    run: () => void;
+};
+/**
+ * One tap on a proposal card, applied inside the update's own transaction
+ * by the bridge (which already proved the live binding, the exact sender
+ * and the exact chat). Returns what to tell Telegram afterwards. The
+ * principal is minted from the binding row against the CURRENT enrolled
+ * ceiling; the door re-proves standing, ceiling, session and the
+ * proposal's own terms again inside its transaction.
+ */
+export declare function applyProposalTap(store: Store, binding: TelegramBinding, token: string, message: {
+    message_id: number;
+    chat?: {
+        id: number;
+    };
+}, repos: readonly string[] | null, options: TelegramConversationOptions, now: Date): {
+    effects: CardEffect[];
+    confirmed: boolean;
+    ignored: boolean;
+};
+/** A handoff card as sent or repainted: its persisted words, plus the one line saying why no link rides it. */
+export type ConversationReport = {
+    answered: number;
+    refused: number;
+    problems: string[];
+};
+/** A part's next attempt after a failed send: bounded backoff by attempt, or Telegram's own retry_after when it named a longer one. */
+export declare const PART_RETRY_MS: readonly [5000, 15000, 60000, 300000];
+/** Unsent parts are retried this long after the message arrived (the card's own lifetime); then the row fails, explicitly unsent. */
+export declare const DELIVERY_MAX_AGE_MS: number;
+export declare function splitParts(text: string): string[];
+/**
+ * Run every claimable queued message for this bot, one at a time, each
+ * outside any SQLite transaction. The caller holds the poll lease and
+ * renews it; the row's own claim is renewed here. Bounded per call so a
+ * flood cannot pin one pass forever.
+ */
+export declare function processTelegramConversations(args: {
+    store: Store;
+    botId: string;
+    transport: Transport;
+    owner: string;
+    clock: () => Date;
+    readProjects: () => Promise<readonly string[]>;
+    options: TelegramConversationOptions;
+    report: ConversationReport;
+    signal?: AbortSignal;
+    limit?: number;
+}): Promise<void>;