toolroll 0.9.17 → 0.9.18

package/dist/browser-workspace.d.ts

@@ -225,6 +225,8 @@ export type BrowserSettingsView = {
     chat?: {
         mode: 'quiet' | 'all';
         digestAt: string | null;
+        /** Whether a result's saved screenshots follow its chat message: off, the first one, or up to 4. */
+        screenshots?: 'off' | 'first' | 'all';
         /** Each project this person can see; a muted one sends no pings but stays in Tasks and the digest. */
         projects?: {
             repo: string;

package/dist/chat-decide.d.ts

@@ -0,0 +1,203 @@
+import { type ModeTerms } from "./modes.js";
+import { type VerifiedApprover } from "./principal.js";
+import type { Scope } from "./scope.js";
+import type { Store } from "./store.js";
+/** The tokens live in chat_decide_action and the open "What should change?" in chat_decide_prompt (store.ts). */
+export type DecideAct = "accept" | "changes" | "retry" | "approve" | "not-now" | "merge";
+export type DecideTarget = {
+    kind: "result";
+    taskId: string;
+    run: number;
+} | {
+    kind: "failed";
+    taskId: string;
+} | {
+    kind: "plan";
+    taskId: string;
+} | {
+    kind: "merge";
+    taskId: string;
+    run: number;
+};
+export type DecideChannel = "telegram" | "slack" | "discord" | "teams";
+/** Who is tapping, where: one paired person's binding on one channel, and the chat the card is in. */
+export type DecideSeat = {
+    channel: DecideChannel;
+    binding: number;
+    chat: string;
+    approver: string;
+    generation: number;
+};
+export type DecideLink = {
+    label: string;
+    path: string;
+};
+/** A button as a channel draws it: an act (its token) or a link to the console. */
+export type DecideButton = {
+    label: string;
+    token: string;
+} | {
+    label: string;
+    link: DecideLink;
+};
+/** The words, said once. */
+export declare const DECIDE_LABELS: {
+    readonly accept: "Accept and finish";
+    readonly changes: "Request changes";
+    readonly retry: "Retry";
+    readonly approve: "Approve & start";
+    readonly "not-now": "Not now";
+    readonly merge: "Merge";
+    readonly look: "Look first";
+    readonly edit: "Edit";
+    readonly yes: "Yes";
+    readonly cancel: "Cancel";
+};
+export declare const WHAT_SHOULD_CHANGE = "What should change?";
+type ActSpec = {
+    act: DecideAct;
+    run: number | null;
+    digest: string;
+};
+/** What a card offers: an optional replacement text (the plan card) and rows of acts and links. */
+export type DecideOffer = {
+    text: string | null;
+    rows: Array<Array<ActSpec | DecideLink>>;
+};
+/** The live mode on this repository, when it lets this person's chat approve: the term signed, by them. */
+export declare function chatApproveMode(store: Store, repo: string | null, approver: string, now: Date): {
+    ok: true;
+    digest: string;
+    terms: ModeTerms;
+} | {
+    ok: false;
+    why: string;
+};
+/** What a plan's yes allows an agent to do, in a few plain words (the approval sheet's "You're allowing"). */
+export declare function permissionPlainWords(profile: Scope["profile"] | null | undefined): string | null;
+/** A plan this person's chat may approve now: the term, the plan's exact bytes, and none of the reasons it must open
+ * Toolroll instead. `digest` binds the scope and the plan document the card shows. */
+export declare function planInChat(store: Store, taskId: string, approver: string, now: Date, root?: string): {
+    ok: true;
+    modeDigest: string;
+    digest: string;
+    scope: Scope;
+} | {
+    ok: false;
+    why: string;
+};
+/** A ready pull request this person's chat may merge now, bound to the exact commit. */
+export declare function mergeInChat(store: Store, taskId: string, run: number, approver: string, now: Date): {
+    ok: true;
+    modeDigest: string;
+    head: string;
+} | {
+    ok: false;
+    why: string;
+};
+/** The plan card: title, goal in two lines, what changes, done when, and what the yes allows. */
+export declare function planCardText(store: Store, taskId: string, scope: Scope, root?: string): string;
+/** The acts a card about this target can take in chat right now, or null when none can (the card keeps its own
+ * link). Reads only; nothing is minted. */
+export declare function decideOffer(store: Store, target: DecideTarget, who: VerifiedApprover, now: Date, root?: string): DecideOffer | null;
+/** One fingerprint of what the card offers, without its tokens: a repaint with the same offer keeps its buttons. */
+export declare function offerFingerprint(offer: DecideOffer): string;
+/** The card's buttons, minted now (message unknown until it is sent: `placeDecideTokens` puts them on it). */
+export declare function mintDecideButtons(store: Store, seat: DecideSeat, target: DecideTarget, offer: DecideOffer, now: Date, message?: string | null): {
+    rows: DecideButton[][];
+    tokens: string[];
+};
+/** Put freshly minted tokens on the message they ride: a tap on any other message proves itself stale. */
+export declare function placeDecideTokens(store: Store, tokens: readonly string[], message: string): void;
+/** Every live button on one message stops working: the card was repainted, or one of its acts was taken. */
+export declare function retireDecideTokens(store: Store, channel: DecideChannel, chat: string, message: string, now: Date): void;
+/** Buttons minted for a send or an edit that didn't land: they never act. */
+export declare function dropDecideTokens(store: Store, tokens: readonly string[], now: Date): void;
+/** Whether a message still carries a button that acts (an offer, or an armed Yes or Cancel): a card whose acts were
+ * all spent, as by Not now, needs fresh ones. */
+export declare function hasLiveDecideTokens(store: Store, channel: DecideChannel, chat: string, message: string, now: Date): boolean;
+export declare function isDecideToken(store: Store, token: string): boolean;
+export type DecideTapOutcome = {
+    ack: string;
+    /** The card repainted: its text and buttons now. */
+    edit?: {
+        text: string;
+        rows: DecideButton[][];
+        tokens: string[];
+    };
+    /** Ask "What should change?": the person's next message is the feedback. `id` names the prompt, so the channel can
+     * record the message it sent (a reply to anything else is not the feedback). */
+    prompt?: {
+        id: number;
+        text: string;
+    };
+    /** Merge after the transaction (GitHub is a network call); the card says "Merging…" until it lands, and
+     * `recordChatMerge` ledgers how it went. */
+    merge?: ChatMerge;
+    ignored?: boolean;
+};
+/** A merge approved in chat, waiting on GitHub: what its ledger line names once the answer is back. */
+export type ChatMerge = {
+    runId: number;
+    taskId: string;
+    by: string;
+    repo: string;
+    via: string;
+};
+/** The links a card keeps once its acts are spent or stale: where to look, never a token. */
+export declare function linksFor(target: DecideTarget): DecideButton[][];
+/**
+ * One tap on a decide button, inside the caller's transaction. Null: not this module's token. The seat must be the
+ * token's own (person, chat, message); a spent, expired or foreign button acts on nothing.
+ */
+export declare function applyDecideTap(store: Store, seat: DecideSeat, input: {
+    token: string;
+    message: string;
+    shown: string;
+    repos: readonly string[];
+    root?: string;
+    now: Date;
+}): DecideTapOutcome | null;
+/** A chat merge's second ledger line, after the GitHub call: merged, or failed and why (its approval is the first). */
+export declare function recordChatMerge(store: Store, merge: ChatMerge, result: {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+}, now: Date): void;
+/** What the card says once the merge came back. */
+export declare function mergedText(shown: string, result: {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+}): string;
+export type DecidePrompt = {
+    id: number;
+    taskId: string;
+    run: number;
+    digest: string;
+    message: string | null;
+};
+/** One open "What should change?" per person and chat: a newer one replaces it. */
+export declare function openDecidePrompt(store: Store, seat: DecideSeat, taskId: string, run: number, digest: string, now: Date): number;
+/** The message that asked "What should change?", once it was sent. */
+export declare function placeDecidePrompt(store: Store, id: number, message: string): void;
+export declare function openPromptFor(store: Store, seat: Pick<DecideSeat, "channel" | "binding" | "chat">, now: Date): DecidePrompt | null;
+/** Whether this message answers the prompt: the person's next message, unless it replies to some other message. */
+export declare function answersPrompt(prompt: DecidePrompt, replyTo: string | null): boolean;
+/** The person's message after "What should change?": a revision of the exact result, with these words as its
+ * feedback, through the result page's own service. Says what was sent, once. */
+export declare function applyDecideFeedback(store: Store, seat: DecideSeat, prompt: DecidePrompt, text: string, repos: readonly string[], root: string | undefined, now: Date): {
+    said: string;
+    link: DecideLink | null;
+};
+/** The link a card keeps when it can't act in chat: a plan's is Review & start, where the password step lives. */
+export declare function decideFallbackLink(target: DecideTarget | null): DecideLink | null;
+/** Which card a pushed notification is, from its recorded kind and task — never from its words. */
+export declare function decideTargetOf(row: {
+    kind: string;
+    taskId: string | null;
+    run: number | null;
+}): DecideTarget | null;
+export {};