toolroll 0.9.103 → 0.9.105

package/dist/chat-follow.d.ts

@@ -1,20 +0,0 @@
-/** A pause that ends early, and quietly, when `signal` aborts. */
-export declare const abortablePause: (signal: AbortSignal) => (ms: number) => Promise<void>;
-/** The most parts one pass delivers (docs/plans/responsive-chat.md §3.5): a reply's parts go together, bounded. */
-export declare const DELIVER_PER_PASS = 5;
-/**
- * Works the queue while this connection stays the current, leased one: each pass first delivers parts already due,
- * then, only when none remain, takes in saved events and plans room messages, delivering up to DELIVER_PER_PASS parts
- * in all, and plans notifications (when they are on), checking it is still current between steps.
- * A pass waits while the connection isn't ready (offline, or the provider asked to retry later).
- */
-export declare function workChatQueue(steps: {
-    same: () => boolean;
-    ready: () => boolean;
-    pause: (ms: number) => Promise<void>;
-    notifications: () => boolean;
-    process: () => Promise<unknown>;
-    rooms: () => Promise<unknown>;
-    deliver: () => Promise<boolean>;
-    notify: () => Promise<unknown>;
-}): Promise<void>;

package/dist/chat-inbox.d.ts

@@ -1,57 +0,0 @@
-import { type ChatApp } from "./flow-triggers.js";
-import { type ChatBinding } from "./chat-delivery-state.js";
-import type { FlowCardSource, FlowTriggerRow, Store } from "./store.js";
-/** "flow 12" or "flow off", after any mention of the bot; Telegram's "/flow 12" or "/flow@bot 12" too. */
-export declare const FLOW_WORDS: RegExp;
-/** A channel's own id: Teams puts the thread's message id on the end of a channel conversation. */
-export declare const channelOf: (app: ChatApp, conversation: string) => string;
-/** The flow a channel feeds, if it feeds one. */
-export declare function watchedChannel(store: Store, app: ChatApp, installation: string, conversation: string): FlowTriggerRow | null;
-/** What a receiver needs to know about a channel message: whether the channel feeds a flow, and whether these are the words that connect one. */
-export declare function channelInbox(store: Store, app: ChatApp, installation: string, conversation: string, text: string): {
-    watched: boolean;
-    command: boolean;
-};
-/** "flow 12" / "flow off" from a paired approver in a channel: connect it to the flow, or stop it feeding one. */
-export declare function connectChannel(store: Store, input: {
-    app: ChatApp;
-    installation: string;
-    conversation: string;
-    binding: Pick<ChatBinding, "id" | "approver">;
-    text: string;
-    repos: readonly string[];
-    followsConversation: boolean;
-}, now: Date): string;
-/**
- * A message in a channel that feeds a flow: a new card (and what to say in
- * its thread), a reply that joins a card's discussion (nothing to say), or
- * why it was left out.
- */
-export declare function takeChannelMessage(store: Store, trigger: FlowTriggerRow, message: {
-    app: ChatApp;
-    conversation: string;
-    ts: string;
-    thread: string;
-    text: string;
-    who: string;
-}, now: Date): {
-    said: string | null;
-    link?: {
-        label: string;
-        path: string;
-    };
-};
-/**
- * Answer in the thread a card came from (an Update zone): one message,
- * through the chat of whoever connected the channel. Idempotent per card
- * visit, so a retried step never answers twice.
- */
-export declare function replyInChannel(store: Store, source: NonNullable<FlowCardSource["chat"]>, visit: {
-    card: number;
-    entry: number;
-}, text: string, now: Date): {
-    ok: true;
-} | {
-    ok: false;
-    said: string;
-};

package/dist/chat-live-schema.d.ts

@@ -1,17 +0,0 @@
-/**
- * v157: live replies in Slack, Discord and Teams (docs/plans/responsive-chat.md §3.2). New tables only, so a saved row
- * reads as it did. Kept beside nothing else so the update road can read the list without loading the store.
- *
- * chat_live: one "Working on it…" message per received event, so the final answer can replace it. Separate from
- * chat_part: planning the reply still adds its own parts (the first one edits this message), and the event stays
- * queued until then. state: creating (asked the app to post it, no answer yet) → placed (its id is known), or
- * uncertain (a crash or a lost answer left it unknown whether it was posted: never posted again), then finalized
- * (the reply was planned onto it) or abandoned (live edits stopped: access changed or the app refused).
- *
- * chat_ack: the 👀 on a person's message, put on when it arrives and taken off once the answer (or the failure
- * notice) is delivered. state: sent (on, to take off later), done (taken off, or nothing to take off: Teams typing),
- * skipped (not put on: the app refused, or it waited too long).
- */
-export declare const V157_SCHEMA = "\nCREATE TABLE IF NOT EXISTS chat_live (\n provider TEXT NOT NULL CHECK (provider IN ('slack','discord','teams')), event TEXT NOT NULL,\n state TEXT NOT NULL CHECK (state IN ('creating','uncertain','placed','finalized','abandoned')),\n message TEXT, generation INTEGER NOT NULL DEFAULT 0, problem TEXT, created TEXT NOT NULL, updated TEXT NOT NULL,\n PRIMARY KEY (provider, event),\n FOREIGN KEY (provider, event) REFERENCES chat_event(provider, id)\n);\nCREATE TABLE IF NOT EXISTS chat_ack (\n provider TEXT NOT NULL CHECK (provider IN ('slack','discord','teams')), event TEXT NOT NULL,\n state TEXT NOT NULL CHECK (state IN ('sent','done','skipped')), created TEXT NOT NULL, updated TEXT NOT NULL,\n PRIMARY KEY (provider, event),\n FOREIGN KEY (provider, event) REFERENCES chat_event(provider, id)\n);\nCREATE INDEX IF NOT EXISTS chat_ack_sent ON chat_ack(provider, state);\n";
-export declare const V157_TABLES: readonly ["chat_live", "chat_ack"];
-export declare const V157_STEPS: readonly ["chat-live-tables"];

package/dist/chat-live.d.ts

@@ -1,161 +0,0 @@
-/**
- * Live replies in Slack, Discord and Teams (docs/plans/responsive-chat.md §3.2, §3.5, slice 3): the 👀 on a person's
- * message when it arrives, and one "Working on it…" message per turn that shows the lead's status and its reply as it
- * is written, then becomes the answer.
- *
- * - The 👀 is put on beside the serial chat queue (a turn there can take a minute), from the saved event, for the
- *   owner's own direct message only, and taken off once the answer or the failure notice is delivered. It carries no
- *   project data: the lease and a live binding are its fence.
- * - The live message is its own `chat_live` row (v157), never a `chat_part`: planning the reply still adds its own
- *   parts, and the first of them edits this message, so the event stays queued until then. Creation is
- *   creating → placed. On Discord a nonce makes a repeated create within its window return the same message, and
- *   a lookup that fails decides nothing; on Slack and Teams an answer that never came leaves the row uncertain, as
- *   does an older Discord create not found among the recent messages. An uncertain message is never posted again (the
- *   reply then posts fresh, and the event's problem says a "Working on it…" may be left above it). That is the
- *   promise: no duplicate, except after an uncertain create.
- * - Edits go through one serialized sender per message (live-reply.ts): one request in flight, the newest view
- *   waiting, closed (and the request in flight settled) before the reply is planned. Every edit re-proves the chat's
- *   standing (`standing`, the same proof final delivery uses), then the lease after it. Once that fails, nothing more is
- *   edited, cleanup included: the last text already ends "(still writing — not final)".
- * - Cosmetic sends share the app's cooldown with durable delivery: none goes while it holds, and a "slow down" on one
- *   sets it for everything. Final parts come first (they never wait on these), then the 👀, then live edits, which
- *   start each app's spacing conservatively and widen it on every "slow down".
- *
- * No live payload carries a button, a card or an ask: those exist only on the planned reply.
- */
-import { type LiveView } from "./live-reply.js";
-import type { LeadProgress } from "./lead-progress.js";
-import { type ShapeOptions } from "./reply-shape.js";
-import type { ChatContent, ChatEvent, ChatState } from "./chat-delivery-state.js";
-export type LivePlatform = "slack" | "discord" | "teams";
-/** The live message's fixed words. */
-export declare const LIVE_WORDS: {
-    readonly working: "Working on it…";
-    readonly notFinal: "(still writing — not final)";
-    readonly continues: "(continues…)";
-    readonly maybeLeft: "A “Working on it…” message may be left above this reply.";
-};
-/** Each app's starting least time between two live edits (§3.5); a "slow down" doubles it, up to the most. */
-export declare const LIVE_SPACING_MS: Readonly<Record<LivePlatform, number>>;
-/** The chat_meta key that says reactions were refused, and when. */
-export declare const ACK_REFUSED_META = "reactions-refused";
-/** What one app does for a live message. Text arrives already rendered in the app's format (`liveText`). */
-export type ChatLiveTransport = {
-    platform: LivePlatform;
-    /** The longest rendered text one live message carries (the reply's first window plus the marker). */
-    limit: number;
-    /** Starting spacing; tests pass 0. */
-    spacingMs?: number;
-    /** Post the live message; resolves its id. Discord sends its nonce, so a repeat returns the same message. */
-    create(text: string): Promise<string>;
-    /** Discord only: the message an unconfirmed create left, found by its nonce, or null (not among the recent ones).
-     * Throws when the lookup itself failed: that is not absence. */
-    recover?(): Promise<string | null>;
-    /** With `recover`: how long after a create a repeat under the same nonce is known to return the same message. */
-    nonceMs?: number;
-    /** Replace the live message's whole text (every field, as the final edit does). */
-    edit(message: string, text: string): Promise<void>;
-    /** The wait an error asks for when it means "slow down", else null. */
-    rateLimited(error: unknown): number | null;
-    /** True when the app may not have done it (the answer was lost). */
-    uncertain(error: unknown): boolean;
-};
-/** A worker's live-reply switch: on, or on with a least spacing between edits (tests pass 0). */
-export type LiveReplies = boolean | {
-    spacingMs: number;
-};
-/** The transport's spacing for that switch (undefined: the app's own start). */
-export declare const liveSpacingOf: (on: LiveReplies | undefined) => number | undefined;
-/** Forget every connection's live spacing (tests). */
-export declare function resetLiveGates(): void;
-/**
- * A view as one live message's text, rendered for the app and measured after rendering: the shaped reply's first
- * window that fits (cut where the final split would cut, never inside a link, code or bold), "(continues…)" when
- * more follows, then the status and the "not final" marker. Null: nothing to show (the turn ended).
- */
-export declare function liveText(view: LiveView, platform: LivePlatform, limit: number, shape?: ShapeOptions): string | null;
-export type LiveRow = {
-    state: "creating" | "uncertain" | "placed" | "finalized" | "abandoned";
-    message: string | null;
-    generation: number;
-    problem: string | null;
-    created: string;
-};
-export declare function liveRow(state: ChatState, event: string): LiveRow | null;
-/** Is this message id the live message of that event (the one its reply's first part edits)? */
-export declare function isLiveMessage(state: ChatState, event: string, message: string | undefined): boolean;
-/**
- * Plan an event's reply (ChatState.plan) onto its live message: when one was placed, the first part edits it, and the
- * row is finalized in the same transaction. An uncertain create (Slack, Teams) leaves the reply to post fresh, and
- * the event's problem says a "Working on it…" may be left above it.
- */
-export declare function planWithLive(state: ChatState, event: string, parts: ChatContent[], now: Date): void;
-export type ChatLiveTurn = {
-    /** Feed one engine event (synchronous, never throws). The first one posts "Working on it…". */
-    push(event: LeadProgress): void;
-    /** The message waits behind earlier ones: post "Waiting for your earlier messages…" unless a live message is up. */
-    queued(): Promise<void>;
-    /** Stop editing: drop the waiting view and settle the request in flight. Resolves before the reply may be planned. */
-    close(): Promise<void>;
-};
-export declare function openChatLive(input: {
-    state: ChatState;
-    event: ChatEvent;
-    installation: string;
-    transport: ChatLiveTransport;
-    /** The owner's message and this app's origin, as the final reply is shaped. */
-    shape: ShapeOptions;
-    /** The lease, the connection and the binding, read locally (no network): the fence for words that carry no data. */
-    fenced: () => boolean;
-    /** The chat's full standing (channelAccess under the turn's ceiling) before an edit that carries the turn's words.
-     * False: refused (nothing more is edited). Throws: no answer now (that view is dropped). */
-    standing: () => Promise<boolean>;
-    now: () => Date;
-}): ChatLiveTurn;
-/** What one app does for the 👀. Teams gives bots no reactions: its ack is "typing…", with nothing to take off. */
-export type ChatAckHooks = {
-    react?: (event: ChatEvent) => Promise<unknown>;
-    unreact?: (event: ChatEvent) => Promise<unknown>;
-    typing?: (event: ChatEvent) => Promise<unknown>;
-    /** This install may not react (a missing permission or scope): stop asking for a while, quietly. */
-    refused: (error: unknown) => boolean;
-    /** Already so: the reaction is already on (when adding) or already gone, with its message (when taking it off). */
-    settled: (error: unknown) => boolean;
-    rateLimited: (error: unknown) => number | null;
-};
-/** Did this install refuse reactions within the last minute? Then no 👀 is asked for (no error after error). */
-export declare function reactionsRefused(state: ChatState, installation: string, now: Date): boolean;
-/**
- * One step of the 👀 work for an installation, beside the queue: take one 👀 off a message whose reply (or failure
- * notice) is delivered, else put one on the next owner's message that arrived. True: it did something (call again).
- */
-export declare function ackPass(input: {
-    state: ChatState;
-    installation: string;
-    owner: string;
-    current: () => boolean;
-    hooks: ChatAckHooks;
-    now: () => Date;
-}): Promise<boolean>;
-/**
- * Before an event's reply is planned: a create that never confirmed (this pass, or before a restart) is found by its
- * nonce on Discord, else marked uncertain, so planning edits the right message or none. False: the lookup failed, so
- * it is still undecided and planning waits (a "slow down" is shared).
- */
-export declare function settleLive(state: ChatState, event: string, transport: ChatLiveTransport | null, now: () => Date): Promise<boolean>;
-/** A cosmetic send (typing…) under the app's shared cooldown: skipped while it holds, and a "slow down" sets it. */
-export declare function underCooldown(state: ChatState, installation: string, rateLimited: (error: unknown) => number | null, now: () => Date, call: () => Promise<unknown>): () => Promise<unknown>;
-/** Forget who was acknowledged when (tests). */
-export declare function resetAckSpacing(): void;
-/**
- * The 👀 loop a worker runs beside its queue while its connection is the current one: a pass every quarter second,
- * and at once when `wake` is called (a message just arrived). Never throws.
- */
-export declare function runChatAcks(input: Omit<Parameters<typeof ackPass>[0], "now"> & {
-    same: () => boolean;
-    signal: AbortSignal;
-    now?: () => Date;
-}): {
-    wake: () => void;
-    done: Promise<void>;
-};

package/dist/chat-message-states.d.ts

@@ -1,75 +0,0 @@
-/**
- * An incoming chat message (a `chat_event` row of kind 'message'): what its states mean, the result words it is
- * settled with, and the one question "which replies have not reached the person yet".
- *
- * States (contracts/chat-tables.ts): queued, running, done, failed, dropped.
- *
- * What `done` means differs by app, and nothing should read more into it than this:
- *  - Telegram: done after every planned part of the reply was sent (or dropped as moot, such as a card whose
- *    proposal was already answered elsewhere). It is written by `ChatMessages.finishMessage`, only by the claim
- *    holder and only from 'running'.
- *  - Slack, Discord and Teams: done as soon as the reply is planned, before any of it is sent. `ChatState.plan`
- *    writes the parts and then `ChatState.finish` marks the row done in the same transaction; the parts go out
- *    later, part by part, through `chat_part`.
- * So `done` means "the message needs no more work from the lead", never "the person has the reply". To ask whether
- * a reply has reached the person, use `unsent()` / `unsentPart()` below, which look at the parts themselves and
- * give the same answer on every app.
- *
- * `failed` is used by Telegram only. `dropped` means the chat was disconnected (or an app gave the event up) while
- * it waited; Telegram rows read a dropped row as failed. Dropped is final: `ChatState.finish` never writes over it,
- * and `ChatState.plan` saves no reply for it.
- */
-import type { ResolvedLead } from "./chat-channel.js";
-import type { LeadFailure, LeadRefusal } from "./lead.js";
-/**
- * Every fixed result word a message row can be written with. These are stored in `chat_event.result`, so each one
- * must stay byte-identical: renaming one would change what older rows mean.
- */
-export declare const CHAT_MESSAGE_OUTCOMES: readonly ["answered", "replayed", "typed-start", "busy", "backlog", "replayed:running", "registry-unavailable", "registry-unavailable:admitted", "delivering", "answered:sending", "unpaired", "unsent:no-session", "replayed:missing", "typed-start:not-counted", "revoked"];
-export type ChatMessageFixedOutcome = (typeof CHAT_MESSAGE_OUTCOMES)[number];
-/** Words a message is queued under while it waits for another attempt (telegram-lead.ts `requeue`). */
-export declare const CHAT_WAIT_OUTCOMES: readonly ["busy", "backlog", "replayed:running", "registry-unavailable", "registry-unavailable:admitted"];
-export type ChatWaitOutcome = (typeof CHAT_WAIT_OUTCOMES)[number];
-/** Waiting for the lead itself (it is answering, or earlier messages wait first): the two-hour bound applies. */
-export declare const CHAT_LEAD_WAITS: readonly ["busy", "backlog"];
-export type ChatLeadWait = (typeof CHAT_LEAD_WAITS)[number];
-/** Waiting on a turn that was already admitted: no age bound (the turn's own deadline ends it). */
-export declare const CHAT_ADMITTED_WAITS: readonly ["replayed:running", "registry-unavailable:admitted"];
-/** The words a row is marked done with (the reply was sent). */
-export type ChatDoneOutcome = "answered" | "replayed" | "typed-start";
-type RefusedReason = LeadRefusal | Extract<ResolvedLead, {
-    ok: false;
-}>["reason"];
-/**
- * Every result word, including the forms that carry a detail after a prefix or a suffix. Build the detailed forms
- * with `chatOutcome` below, never by joining strings at the call site.
- */
-export type ChatMessageOutcome = ChatMessageFixedOutcome | `${ChatWaitOutcome}:gave-up` | `refused:${RefusedReason}` | `failed:${LeadFailure}` | `replayed:${string}` | `unsent:gave-up:${string}` | `unsent:${string}`;
-/** Builders for the result words that carry a detail. The stored text is exactly what the old string joins wrote. */
-export declare const chatOutcome: {
-    /** A wait that ran past its age bound. */
-    readonly gaveUp: <W extends ChatWaitOutcome>(wait: W) => `${W}:gave-up`;
-    /** The lead refused the turn, or no session could be resolved for it. */
-    readonly refused: <R extends RefusedReason>(reason: R) => `refused:${R}`;
-    /** The turn ran and failed. */
-    readonly failed: <R extends LeadFailure>(reason: R) => `failed:${R}`;
-    /** The recovered turn had ended without an answer: its failure reason as the turn row stores it ("failed" when none). */
-    readonly replayedFailed: (reason: string | null) => `replayed:${string}`;
-    /** The reply could not go out: the chat or its projects changed (the problem in words). */
-    readonly unsent: (problem: string) => `unsent:${string}`;
-    /** The reply was still unsent a day after it was planned (the last send error, or "unsent"). */
-    readonly unsentGaveUp: (error: string | null) => `unsent:gave-up:${string}`;
-};
-/** Is this word one of the waits for the lead itself (busy or backlog)? */
-export declare function isLeadWait(outcome: string | null): outcome is ChatLeadWait;
-/** Is this word a wait on a turn that was already admitted (no age bound)? */
-export declare function isAdmittedWait(outcome: string | null): boolean;
-/** SQL: this `chat_part` row (by its alias) has not reached the person: planned and neither sent nor dropped. */
-export declare function unsentPart(part: string): string;
-/**
- * SQL: the `chat_event` row (by its alias or table name) has a reply part that has not reached the person yet.
- * The one answer to "is anything of this reply unsent?" on every app; wrap it in NOT for "everything reached them
- * or was dropped". `part` names the inner alias when the caller's query already uses the default.
- */
-export declare function unsent(event: string, part?: string): string;
-export {};