@primusclaw/personal-agent 0.0.0-stage → 0.1.1

package/dist/types/review/connect/github-connect.d.ts

@@ -0,0 +1,50 @@
+import type { Random } from "../../ports/random.js";
+import type { Conversation, UserRef } from "../../ports/surface.js";
+import type { ReviewDeps } from "../service/deps.js";
+import type { GithubAccount } from "../service/account.js";
+/** Claw said it reads this person's GitHub: no need to ask again for this long. */
+export declare const CONNECTED_MS = 600000;
+/** "Not now": no card for this long. */
+export declare const DECLINED_MS: number;
+/** A card was offered: no other for this long, whatever became of it. */
+export declare const SHOWN_MS: number;
+export interface ConnectRequest {
+    readonly sender: UserRef;
+    readonly credential: string;
+    readonly text: string;
+    readonly lang: "zh" | "en";
+    readonly conversation: Conversation;
+    readonly again: () => Promise<void>;
+}
+export declare class GithubConnect {
+    private readonly deps;
+    private readonly account;
+    private readonly random;
+    private readonly connected;
+    private readonly quiet;
+    private readonly offered;
+    private readonly narrowHint;
+    private readonly wide;
+    private readonly hinting;
+    private readonly hints;
+    constructor(deps: ReviewDeps, account: GithubAccount, random: Random);
+    private now;
+    /** Settles when the scope hints started so far have ended. */
+    idle(): Promise<void>;
+    /** The person changed their GitHub connection: what was remembered of it is asked again next time. */
+    forget(userId: string): void;
+    /** Offers the connect card for a question about the person's own GitHub when Claw cannot read it yet; true when sent. */
+    offer(request: ConnectRequest): Promise<boolean>;
+    private sendCard;
+    private until;
+    /** The scope line is looked for in the background: the message goes on at once; one look at a time per person. */
+    private startHint;
+    /** The device flow of a card ended: once connected, the question is asked again. */
+    private bound;
+    /** "Not now": the card closes, the question is not asked again, and no card is offered for a day. */
+    dismiss(sender: UserRef, data: Readonly<Record<string, unknown>>, lang: "zh" | "en", settle: (text: string) => Promise<unknown>): Promise<void>;
+    /** The scope line, when Claw reads this person's GitHub with their binding; never throws. */
+    private maybeHint;
+    /** The binding reads public repositories only and the message names one GitHub does not show publicly: one line says so. */
+    private hintWiderScope;
+}

package/dist/types/review/connect/questions.d.ts

@@ -0,0 +1,6 @@
+export declare const MAX_QUESTION_CHARS = 2000;
+export declare const MAX_REPOS_LOOKED_AT = 3;
+/** Whether a message asks about the state of the person's own GitHub (a GitHub word, the person, a word of state). */
+export declare function asksAboutOwnGithub(text: string): boolean;
+/** The repositories a message names, each once, in order: a github.com link, or owner/name in a message with a GitHub word. */
+export declare function repositoriesNamed(text: string): [string, string][];

package/dist/types/review/connect/review-ask.d.ts

@@ -0,0 +1 @@
+export declare function asksForReview(text: string): boolean;

package/dist/types/review/consent.d.ts

@@ -0,0 +1,13 @@
+/** What a person agrees to with `/github bind`, and how `/github status` says what Clawy reads their GitHub with. */
+import type { GithubConnection } from "../claw/model.js";
+import type { DeviceCode } from "../ports/github.js";
+export declare const MAX_DEVICE_WAIT_SECONDS: number;
+/** The minutes a code is good for, as the person is told it. */
+export declare function codeMinutes(code: DeviceCode): number;
+/**
+ * What `/github bind` asks the person to agree to, Chinese then English. `reads`: Claw reads GitHub with the binding too
+ * (or could not say whether it does: then the wider use is what they are told), so the consent says that.
+ */
+export declare function consentText(code: DeviceCode, reads: boolean): string;
+/** The line of `/github status` that says whether Clawy reads the person's GitHub with this binding, as Claw says it. */
+export declare function readsLine(connection: GithubConnection | null, known: boolean): string;

package/dist/types/review/handoff.d.ts

@@ -0,0 +1,22 @@
+import type { PullRef } from "../claw/model.js";
+export declare const MAX_PULLS_PER_REQUEST = 30;
+export declare const HELD_SAYS_MAX = 5;
+export declare const HELD_SAY_MAX_CHARS = 4000;
+/** What Claw takes of the asker's own words (`requester_note`), which it quotes to the reviewer as untrusted. */
+export declare const REQUESTER_NOTE_MAX = 2000;
+/** The handoff a 1:1 message declares (`channel_context.handoffs`) and Claw names its action with. */
+export declare const REVIEW_HANDOFF = "review_for_other";
+export interface ReviewHandoff {
+    readonly reviewerUserId: string;
+    readonly reviewerName: string;
+    readonly pulls: readonly PullRef[];
+    readonly merge: boolean;
+    /** The person's own message, quoted to the reviewer as untrusted. */
+    readonly note: string;
+    /** The record Claw kept of the handoff, echoed when the review is started ('' from a Claw that sends none). */
+    readonly handoffId: string;
+    /** What the assistant said in the same turn before handing this over: the answer to the handoff carries it. */
+    readonly said: readonly string[];
+}
+/** The `review` of an `assistant.action`, or undefined when it is not one in every field. */
+export declare function parseReviewHandoff(raw: unknown): ReviewHandoff | undefined;

package/dist/types/review/held.d.ts

@@ -0,0 +1,15 @@
+import type { PullRef } from "../claw/model.js";
+export declare const CONFIRMATION_FALLBACK_SECONDS = 3600;
+export declare const CONFIRMATION_MAX_SECONDS: number;
+export declare const MAX_CONFIRMATIONS_PER_TURN = 3;
+/** What a held review can be (Claw holds a high-risk approval; a card shows whichever it holds). */
+export declare const REVIEW_EVENTS: readonly string[];
+/**
+ * When Claw says a confirmation runs out, as epoch seconds: never later than a day from now, and a short life when it does
+ * not say, or says something that is not a time with an offset.
+ */
+export declare function expiryOf(value: unknown, now: number): number;
+/** Claw's confirmation names this very pull request (a record that names none is not one that does). */
+export declare function namesPull(item: Readonly<Record<string, unknown>>, pull: PullRef): boolean;
+/** The review a confirmation of kind `review` holds (`{event, body, comments}`), or undefined when a card cannot show it. */
+export declare function heldReview(item: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> | undefined;

package/dist/types/review/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The GitHub review delegation: a colleague reviews (and, when it is safe, merges) a public pull request as the person who
+ * was named for it, on that person's own GitHub account, which only Claw's restricted review tools use on the server.
+ */
+export * from "./views.js";
+export { REVIEW_MODE_NAMES, isReviewMode, type ReviewMode } from "./review-turn.js";
+export { connectionsText, UNKNOWN, type ConnectionsInput } from "./connect/connections.js";
+export { GithubReview } from "./service/github-review.js";
+export { ReviewHandoffAction, type HandoffActionDeps } from "./service/handoff-action.js";
+export type { ReviewDeps, ReviewHost, StartReviewTurn, Guard, Audit, FollowWire, RestoreRef } from "./service/deps.js";
+export type { PostWorkCard } from "./service/notices.js";
+export { reviewTurnStart, routedReviewTurns, type AfterReviewTurn, type StartRouterTurn, } from "./service/routed-turn.js";
+export { parseReviewHandoff, REVIEW_HANDOFF, type ReviewHandoff } from "./handoff.js";
+export type { ReviewTurn } from "./review-turn.js";

package/dist/types/review/intent-check.d.ts

@@ -0,0 +1,36 @@
+import { type Mention } from "../review-text/names.js";
+import { type PullKey } from "../review-text/pull-ref.js";
+import type { PullRef } from "../claw/model.js";
+import { type ReviewAsk } from "./request-parse.js";
+export declare const INTENTS: readonly ["review_merge", "review", "none"];
+/** What the reading comes to. */
+export type IntentVerdict = 
+/** Not a request to review: chat, as ever. */
+{
+    readonly kind: "chat";
+}
+/** The one question to ask back. */
+ | {
+    readonly kind: "question";
+    readonly text: string;
+} | {
+    readonly kind: "ask";
+    readonly ask: ReviewAsk;
+}
+/** The answer is no reading at all (not JSON, an unknown intent, a field of the wrong type): the rules read it. */
+ | {
+    readonly kind: "unreadable";
+    readonly why: string;
+};
+/**
+ * Which of the message's pull requests (`keys`) one entry of the model's "prs" is: a link or owner/repo#N, or a number as
+ * the asker wrote it ("245", "#245", "PR 245", "PrimusClaw#245") when exactly one of them has that number (and that
+ * repository, when one is written).
+ */
+export declare function pullsWritten(item: string, keys: ReadonlySet<PullKey>): Set<PullKey>;
+/**
+ * The model's reading of a request, held to the message. `text` is what the asker wrote (with the addresses behind its
+ * links), never a message it quotes: a quote may name the pull requests (`found` is read from it too), never the reviewer
+ * or the model. `direct`: a 1:1 chat, where naming nobody means the asker.
+ */
+export declare function checkIntent(raw: Readonly<Record<string, unknown>>, text: string, mentions: readonly Mention[], found: readonly PullRef[], direct?: boolean): IntentVerdict;

package/dist/types/review/outcome.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How Claw's answer to a held write reads to the reviewer (the card that replaces the click) and to the group, in that
+ * order. A status that is not the kind's own (`merged` for a merge, `submitted` for a review) is a refusal and says why when
+ * Claw did; a merge put in the base branch's merge queue is queued, never merged; and a try that already wrote to GitHub is
+ * never said not to have happened.
+ */
+import type { PublicErrors } from "../public-error/public-errors.js";
+/** What one confirmation flow says for what Claw holds: only these sentences differ between a merge and a review. */
+export interface HeldWords {
+    /** Of the note card that replaces a click. */
+    readonly title: string;
+    /** What is acted on. */
+    readonly thing: string;
+    /** What did not happen when it was refused. */
+    readonly verb: string;
+    /** The status Claw answers when it did. */
+    readonly done: string;
+    readonly review: boolean;
+}
+/** The held write a confirmation row records. */
+export interface HeldRow {
+    readonly repo: string;
+    readonly pr: number;
+    readonly kind: string;
+    readonly event: string;
+}
+export declare function heldWords(row: HeldRow): HeldWords;
+export type Lines = readonly [card: string, group: string];
+/** A merge Claw put in the merge queue: queued, and not merged (the queue merges it, or takes it out, later). */
+export declare function queuedLines(pull: string, name: string, outcome: Readonly<Record<string, unknown>>): Lines;
+/** The lines for a reason Claw's gates name when an allowed write was refused anyway; undefined keeps the generic line. */
+export declare function refusalLines(reason: string, pull: string, name: string, review: boolean, outcome: Readonly<Record<string, unknown>>, errors: PublicErrors): Lines | undefined;
+/** How Claw's answer to a decision reads: [the reviewer's card, the group]. */
+export declare function outcomeLines(row: HeldRow, words: HeldWords, outcome: Readonly<Record<string, unknown>>, name: string, errors: PublicErrors): Lines;
+/** "3 passed, 1 failed, 2 pending" of a confirmation's checks ('' when Claw gave none). */
+export declare function checksText(checks: unknown): string;

package/dist/types/review/progress.d.ts

@@ -0,0 +1,50 @@
+/**
+ * How the asker of a review someone else runs hears of it: only its asker view (state, link, conclusion, merged, what a
+ * waiting one waits for, what it found), as one line for one review, or one message for a request's several. And what the
+ * reviewer hears when the reviews asked of them end. `viewStage` is the key that changes exactly when there is news.
+ */
+import type { AskerView, PullRef } from "../claw/model.js";
+import { type ReviewTurn } from "./review-turn.js";
+export declare const ITEM_STOPPED_ZH = "\u5DF2\u505C\u6B62";
+/** One review someone else runs while its asker follows it. */
+export interface Followed {
+    readonly review: ReviewTurn;
+    /** What the asker was told of it last (`viewStage`). */
+    said: string;
+    /** Its reviewer was told it waits for them. */
+    reviewerTold: boolean;
+    /** Followed again after a restart: this worker has no card of it to close. */
+    readonly resumed: boolean;
+    /** Claw said it waits for a slot: only then is its start news. */
+    seenQueued: boolean;
+}
+export declare function followedItemId(entry: Followed): string;
+/** The words of how a view stands: its conclusion and whether it merged, or how it ended. */
+export declare function viewWords(view: AskerView): string;
+/** Claw's `pr_url` when it is a pull request's address, else the address of the pull request the request named. */
+export declare function shownPrUrl(prUrl: string, pull: PullRef): string;
+/** What the asker of a review someone else ran hears of it, once. */
+export declare function requesterResultText(review: ReviewTurn, view: AskerView): string;
+/** How a review item ended, as its card in the asker's chat shows it once its Stop is gone. */
+export declare function itemEndText(view: AskerView): string;
+/** How a review of one's own ended, as its card shows it: from what its turn left on GitHub. */
+export declare function ownItemEndText(review: ReviewTurn): string;
+/** What the reviewer hears when a review asked of them ends. */
+export declare function reviewerResultText(review: ReviewTurn, view: AskerView): string;
+/** What the asker has been told of a review, as a key that changes exactly when there is news ('' nothing yet). */
+export declare function viewStage(view: AskerView): string;
+/** `viewStage` for one followed review, with one more piece of news: a review that waited for a slot has 'started'. */
+export declare function entryStage(entry: Followed, view: AskerView): string;
+/** The conclusion a `viewStage` key holds ('' none). */
+export declare function stageVerdict(stage: string): string;
+/** How a review someone else runs stands, as its asker is told. `started`: it waited for a slot, and has just started. */
+export declare function progressWords(review: ReviewTurn, view: AskerView, started?: boolean): string;
+/**
+ * One message for what is news of a request's reviews asked of someone else: one line for a request of one review; for
+ * several, a count of how many have a conclusion and how many ended, then the news, then what the others are doing.
+ */
+export declare function progressText(entries: readonly Followed[], told: readonly (readonly [Followed, AskerView])[]): string;
+/** The asker's last line when the reviews they follow are still open at the deadline. */
+export declare function unfinishedText(left: readonly Followed[]): string;
+/** What the reviewer hears when reviews asked of them end. */
+export declare function reviewerEndedText(ended: readonly (readonly [Followed, AskerView])[]): string;

package/dist/types/review/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { ReviewTurn } from "./review-turn.js";
+export declare function reviewPrompt(review: ReviewTurn): string;

package/dist/types/review/receipt.d.ts

@@ -0,0 +1,45 @@
+import type { GithubOutcome } from "../turn/github-outcome.js";
+import { type ReviewTurn } from "./review-turn.js";
+export declare const SUMMARY_CHARS = 1200;
+export declare const DM_SUMMARY_CHARS = 700;
+/** One call of a write tool, as the stream showed it: the tool, the status it answered, the review's event. */
+export type ToolResult = GithubOutcome;
+/**
+ * The text with each tool name or state the model wrote by its code said in plain words, in Chinese when the text has any
+ * Chinese. A line that has a file:line is a finding about the code under review: it is left as it is.
+ */
+export declare function plainWords(text: string): string;
+/** A model id as shown: a model id's characters only, at most 100 (it may come from the gateway). */
+export declare function modelId(model: string, limit?: number): string;
+/** The one line that says which model a review ran on, and that it ran under the reviewer's fully automatic setting. */
+export declare function modelNote(model: string, zh: boolean, autoOfName?: string): string;
+/** At most `limit` characters of `text`, said to be shortened, with a link to the whole answer when there is one. */
+export declare function clipSummary(text: string, limit: number, link?: string): string;
+/** The answer without its last line when that is the VERDICT line. */
+export declare function withoutVerdict(answer: string): string;
+/** What a group is told of an answer: without its verdict line, in plain words, at most SUMMARY_CHARS, and the model note. */
+export declare function shapeGroupAnswer(answer: string, options?: {
+    link?: string;
+    model?: string;
+    autoOf?: string;
+}): string;
+/**
+ * The one line that says how a review came out, shown the moment the stream shows it. undefined when this call does not
+ * settle it: a review that may merge is settled by the merge call (or by a review held or asking for changes), a review
+ * only by the review call.
+ */
+export declare function resultLine(review: ReviewTurn, outcome: ToolResult, model: string): string | undefined;
+/**
+ * The head of a review's one message: the verdict, whether it merged, how many inline comments it left, the model and the
+ * link, from every result the stream showed (the last review call for the verdict, the last merge call for the merge).
+ */
+export declare function reviewHeadline(review: ReviewTurn, results: readonly ToolResult[], comments: number, model: string, lang?: "zh" | "en" | ""): string;
+export interface AnswerParts {
+    readonly link?: string;
+    readonly model?: string;
+    readonly results?: readonly ToolResult[];
+    readonly comments?: number;
+    readonly prSummary?: string;
+}
+/** A review's ONE message where it was asked: the headline, the summary line, then the answer in plain words. */
+export declare function reviewAnswer(review: ReviewTurn, answer: string, parts: AnswerParts): string;

package/dist/types/review/refusals.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What the asker is told when Claw starts none, or only some, of a request's reviews, and the acknowledgement's notes of
+ * what Claw made: each item's number, which wait for a slot and why, how the merges will be made, and the model Claw chose.
+ * Everything here is from Claw's answer, never from what a model said.
+ */
+import type { ReviewsRefused } from "../claw/errors.js";
+import type { PublicErrors } from "../public-error/public-errors.js";
+import type { PullRef } from "../claw/model.js";
+import { type ReviewTurn } from "./review-turn.js";
+/** One request may name this many pull requests; each is reviewed in a session of its own. */
+export declare const MAX_PULLS_PER_REQUEST = 30;
+/** ... of which this many start at once; Claw queues the rest and starts each as one of the request's ends. */
+export declare const REVIEWS_STARTED_AT_ONCE = 10;
+export declare const MAX_MODELS_LISTED = 30;
+export declare const ALREADY = "\u5DF2\u7ECF\u5728 review \u4E2D";
+/** Why Claw would not start a review of one pull request (`pr_check_failed`), as the asker is told it. */
+export declare const PR_CHECK_REASONS: Readonly<Record<string, string>>;
+/** ... and why it would start none for this reviewer: no pull request of theirs would fare better on its own. */
+export declare const REVIEWER_REASONS: Readonly<Record<string, (who: string) => string>>;
+/** A refusal of one pull request of the request. */
+export declare const ONE_PULL: readonly string[];
+/** The reasons Claw gives for refusing a service's answer for a person, said as such. */
+export declare const SERVICE_REFUSAL_REASONS: Readonly<Record<string, string>>;
+/** The sentence for a refusal of Claw's: its reason (a word it does not name is the last one) and what was not done. */
+export declare function serviceRefusal(code: string, undone: string): string;
+/** What the asker is told when Claw started none of the reviews. */
+export declare function batchRefusal(err: ReviewsRefused, who: string, count: number, errors: PublicErrors): string;
+/** Why a review waits for a slot, in the words of whoever is told: the asker, or the reviewer. */
+export declare function queueReason(reason: string, reviewer: string, requester?: string, toReviewer?: boolean): string;
+/** The items Claw made for these reviews, by number, and which wait for a slot and why ('' when Claw made none). */
+export declare function itemsNote(reviews: readonly ReviewTurn[], who: string): string;
+export declare function shorts(pulls: readonly PullRef[]): string;
+export declare function refusedText(refused: readonly (readonly [PullRef, string])[]): string;
+/**
+ * What the receipt adds about the model when Claw chose it otherwise than asked: the model it was to run on and cannot (the
+ * key that pays cannot use it), or a model the asker named for a review someone else runs on their own settings. '' else.
+ */
+export declare function modelChosenNote(review: ReviewTurn, who: string, asked: string): string;
+/**
+ * What the receipt says of how the merges will be made: only what the reviews started say. Every one waits for the
+ * reviewer's confirmation: that, plainly. Otherwise the reviewer's fully automatic setting is said, a held one among the
+ * others is named, and a merge Claw makes with the asker's own account is said. '' when there is nothing to say.
+ */
+export declare function mergeLine(reviews: readonly ReviewTurn[], who: string, merge: boolean, auto: boolean): string;

package/dist/types/review/request-parse.d.ts

@@ -0,0 +1,40 @@
+import { type Mention } from "../review-text/names.js";
+import type { PullRef } from "../claw/model.js";
+/** What a request says. */
+export interface ReviewAsk {
+    /** The text between 请 and 帮我, markers kept and the model taken out; '' when nobody was named. */
+    readonly who: string;
+    readonly mentions: readonly Mention[];
+    /** The distinct pull requests it points at, in the order it names them. */
+    readonly pulls: readonly PullRef[];
+    /** The distinct models it names ("用 X 帮我 review", "model: X"); none: the default. */
+    readonly models: readonly string[];
+    /** Who each later "请 XX review 合入 ..." of the same message names. */
+    readonly again: readonly string[];
+    /** The channel ids of everyone the message names or mentions (set once that is checked). */
+    readonly named: readonly string[];
+    /** The repository bare numbers were read as; '' when none were. */
+    readonly repo: string;
+    /** Numbers written on their own that were not taken as pull requests: named in the acknowledgement. */
+    readonly unread: readonly number[];
+    /** False: a review only, never a merge. */
+    readonly merge: boolean;
+    /** The record Claw kept of a review the assistant handed back; '' for a typed request. */
+    readonly handoffId: string;
+}
+export declare function reviewAsk(fields: Partial<ReviewAsk> & Pick<ReviewAsk, "who" | "pulls">): ReviewAsk;
+/**
+ * A named request is read only when its "review 合入" starts within this many code points of the text (Python
+ * `MAX_ASK_HEAD_CHARS`): the name before it is a few words, and a long list of pull requests may follow it.
+ */
+export declare const NAMED_ASK_MAX = 1000;
+/**
+ * The request a message makes, or undefined when it is not one. It is one when it says 请 ... 帮我 review 合入, or says
+ * "review 合入" and points at a pull request; a review only when it says 请 XX 帮我 review <PR> with no word of merging.
+ */
+export declare function parseReviewAsk(text: string, mentions: readonly Mention[]): ReviewAsk | undefined;
+/**
+ * The names a later line of the same message gives that are not the person the first line names (a mention is the person
+ * its id says, whatever its display name). A line that names nobody says nothing about it.
+ */
+export declare function otherReviewers(ask: ReviewAsk): string[];

package/dist/types/review/review-turn.d.ts

@@ -0,0 +1,83 @@
+/**
+ * One review while it runs: who asked, for whom, where the asker and the reviewer are reached, and what Claw made of it.
+ * Mutable on purpose, as the Python worker's `ReviewTurn`: the turn fills in what it left on GitHub, the model it ran on and
+ * the pull request's one-line summary as it learns them.
+ */
+import type { AskerView, ReviewStart, PullRef } from "../claw/model.js";
+import type { JsonObject } from "../json.js";
+import type { ConversationRef } from "../ports/surface.js";
+export type ReviewMode = "high_risk_confirm" | "fully_auto";
+export declare const DEFAULT_MODE: ReviewMode;
+export declare const REVIEW_MODE_NAMES: readonly ReviewMode[];
+export declare function isReviewMode(value: unknown): value is ReviewMode;
+/** What a turn left on GitHub: the tool, the status it answered and the review's event ("" none). */
+export type Wrote = readonly [tool: string, status: string, event: string];
+export interface ReviewTurn {
+    readonly requesterId: string;
+    readonly requesterName: string;
+    readonly requesterChannelId: string;
+    readonly actorId: string;
+    /** The reviewer's Claw user id. */
+    actorUserId: string;
+    readonly actorName: string;
+    readonly actorChannelId: string;
+    readonly pull: PullRef;
+    /** Where the request was asked (the group's, or the asker's own chat). */
+    readonly asked: ConversationRef | undefined;
+    /** Set when Claw has made the session. */
+    sessionId: string;
+    /** The model the request named ('' the default); Claw's own once it says (`modelReported`). */
+    model: string;
+    modelReported: boolean;
+    /** The reviewer's confirmation setting when the review started. */
+    reviewMode: ReviewMode;
+    /** Every merge waits for the reviewer's own confirmation, whatever their setting. */
+    mergeHeld: boolean;
+    /** The pull request's title as GitHub's public read gave it ('' not read). */
+    readonly title: string;
+    /** The chat it was asked in, as the reviewer's notice names it (the group's name, "群聊" or "私聊"). */
+    readonly where: string;
+    readonly fromGroup: boolean;
+    readonly lang: "zh" | "en";
+    /** What the turn left on GitHub (set after the turn). */
+    wrote: Wrote[];
+    /** The turn's sentence of what the pull request does (set after the turn). */
+    prSummary: string;
+    /** The model the turn ran on ('' the default; set after the turn). */
+    ranModel: string;
+    readonly reviewOnly: boolean;
+    /** The reviewer's GitHub login, as the identity service named it when the review started. */
+    readonly actorLogin: string;
+    /** The review item Claw made for it; undefined: the session was made here. */
+    item: ReviewStart | undefined;
+    /** The item is the reviewer's own (asked of someone else): followed by its asker view, never its session. */
+    forReviewer: boolean;
+    /**
+     * A review asked of someone else whose session is made here because Claw answered 404: asks Claw once more for it as the
+     * reviewer's item when the session is then refused. True: the asker was told; false: the turn says its own failure.
+     */
+    asItem: (() => Promise<boolean>) | undefined;
+    /** The acknowledgement shown at the top of the review's progress message ('' nothing to acknowledge). */
+    ack: string;
+}
+export type NewReviewTurn = Pick<ReviewTurn, "requesterId" | "requesterName" | "actorId" | "actorUserId" | "actorName" | "actorChannelId" | "pull"> & Partial<ReviewTurn>;
+export declare function reviewTurn(fields: NewReviewTurn): ReviewTurn;
+export declare function selfReview(review: ReviewTurn): boolean;
+/** The reviewer's name when the review runs under their fully automatic setting (and nothing holds its merge), else ''. */
+export declare function autoOf(review: ReviewTurn): string;
+/** The reviewer's name as the asker reads it ("对方" when there is none). */
+export declare function reviewerName(review: ReviewTurn): string;
+/** The asker's name as the reviewer reads it ("有同事" when there is none). */
+export declare function askerName(review: ReviewTurn): string;
+export declare function viewFinished(view: AskerView): boolean;
+export declare function viewWaitsForReviewer(view: AskerView): boolean;
+/**
+ * What is kept of a followed review (`asker_follows.review`): names, chats and the pull request, never a credential. The
+ * JSON keys are the Python worker's, so either worker reads what the other wrote. `wire` carries the reply-address fields
+ * the channel needs to open the reviewer's chat (Teams: service url, tenant, bot id), kept as the channel gave them.
+ */
+export declare function followRecord(review: ReviewTurn, wire: JsonObject): JsonObject;
+/** A followed review again, from what was kept of it; undefined when it cannot be read (it is then let go). */
+export declare function reviewOfRecord(raw: unknown): ReviewTurn | undefined;
+/** A display name as it is kept on one line (at most 100 characters). */
+export declare function keptName(name: string): string;

package/dist/types/review/service/account.d.ts

@@ -0,0 +1,52 @@
+import { type CredentialFailure, type DeviceCode } from "../../ports/github.js";
+import type { Conversation, OutMessage, UserRef } from "../../ports/surface.js";
+import { type ReviewMode } from "../review-turn.js";
+import type { ReviewDeps } from "./deps.js";
+/** `(connected, login)` once a device flow has ended, for a question that waited for it. */
+export type OnBound = (connected: boolean, login: string) => Promise<void>;
+export declare class GithubAccount {
+    private readonly deps;
+    /** Teams user -> the device flow that waits for their approval. */
+    private readonly binding;
+    /** Teams user -> the confirmation setting chosen while their binding is made. */
+    private readonly modeChosen;
+    constructor(deps: ReviewDeps);
+    /** Settles when every device flow started so far has ended (for tests and an orderly stop). */
+    idle(): Promise<void>;
+    /** `/github ...` in a 1:1 chat. */
+    command(sender: UserRef, args: string, conversation: Conversation): Promise<void>;
+    private run;
+    /** The identity service does not know this chat's user: they connect their Primus account first, then ask again. */
+    connectFirst(sender: UserRef, conversation: Conversation): Promise<void>;
+    private waiting;
+    private bind;
+    /**
+     * The device flow started for a question that needs the person's GitHub (the connect card shows the code): the code, or
+     * undefined when there is nothing to start (connected already, a code already waits, or GitHub gave none). `onDone` runs
+     * once when the flow ends; the default confirmation applies. A failure of the identity service is returned.
+     */
+    bindForQuestion(sender: UserRef, conversation: Conversation, onDone: OnBound): Promise<DeviceCode | CredentialFailure | undefined>;
+    private startBinding;
+    /** Waits for the approval and hands the token to the identity service, in memory only. */
+    private finishBind;
+    /** (connected, the GitHub login) once the flow has ended; every way it can end is said to the person here. */
+    private waitAndBind;
+    private bindRefusal;
+    /** What the person is told once GitHub is connected: the review settings, or (`short`, a question waits) one line. */
+    private bound;
+    /** A click on one of the two confirmation settings: the clicker's own binding is the only one changed. */
+    modeClick(sender: UserRef, data: Readonly<Record<string, unknown>>, settle: (text: string) => Promise<unknown>, conversation: Conversation): Promise<void>;
+    /**
+     * The one way a person's choice of a confirmation setting is carried out, pressed or typed: while their binding is being
+     * made it waits for it; otherwise it is written now, as them. (What they are told, and whether to connect first.)
+     */
+    chooseMode(sender: UserRef, mode: ReviewMode): Promise<readonly [string, boolean]>;
+    /** The confirmation-setting card; it says how to answer by typing until a click of the person's has arrived. */
+    modeCard(userId: string, current: ReviewMode | "", suggested: ReviewMode | "", lead: string): OutMessage;
+    private mode;
+    /** Shows the card for a 1:1 message that asked about the setting (`suggested`: the one asked for; undefined: show it). */
+    showMode(sender: UserRef, suggested: ReviewMode | "" | "show", conversation: Conversation): Promise<void>;
+    private unbind;
+    status(sender: UserRef, conversation: Conversation): Promise<CredentialFailure | undefined>;
+    private autoMerge;
+}

package/dist/types/review/service/chat.d.ts

@@ -0,0 +1,18 @@
+import { type Conversation, type ConversationRef, type OutMessage } from "../../ports/surface.js";
+import type { ReviewDeps } from "./deps.js";
+export declare function say(deps: ReviewDeps, conversation: Conversation, text: string): Promise<void>;
+/** `say`, logging instead of failing: for a line that must not end the flow that sends it. */
+export declare function sayQuietly(deps: ReviewDeps, conversation: Conversation, text: string, what: string): Promise<boolean>;
+export declare function send(conversation: Conversation, message: OutMessage): Promise<void>;
+/** The conversation a stored reference points at, or undefined when it cannot be read. */
+export declare function stored(deps: ReviewDeps, reference: unknown): Conversation | undefined;
+/** Who a person is, to reach their own chat. */
+export interface Reachable {
+    readonly userId: string;
+    readonly channelUserId: string;
+}
+/**
+ * A conversation into this person's 1:1 chat with the bot: the one the store knows, else one the channel opens through
+ * `via` (a conversation both are in). undefined when neither works.
+ */
+export declare function personalChat(deps: ReviewDeps, person: Reachable, via: ConversationRef | undefined): Promise<Conversation | undefined>;

package/dist/types/review/service/confirm.d.ts

@@ -0,0 +1,49 @@
+import type { GithubConfirmation } from "../../ports/store/github.js";
+import type { Conversation, OutMessage, UserRef } from "../../ports/surface.js";
+import type { ReviewTurn } from "../review-turn.js";
+import type { ReviewDeps } from "./deps.js";
+import type { GithubAccount } from "./account.js";
+import type { Notices } from "./notices.js";
+/** How an answer to a held write ended. */
+export interface Answered {
+    /** What the person is told. */
+    readonly text: string;
+    /** Still pending: the buttons stay, and they may answer again. */
+    readonly open: boolean;
+    /** They must connect their Primus account first. */
+    readonly connect: boolean;
+    /** What the group that asked is told ('' none). */
+    readonly group: string;
+}
+/** How a click is settled (the router's `ClickRoute.settle`). */
+export type Settle = (card: OutMessage | string, fallback?: string) => Promise<unknown>;
+export declare class HeldWrites {
+    private readonly deps;
+    private readonly notices;
+    private readonly account;
+    constructor(deps: ReviewDeps, notices: Notices, account: GithubAccount);
+    /** One write Claw holds, offered to the reviewer; a record that is not for this review is not sent. */
+    offer(review: ReviewTurn, item: Readonly<Record<string, unknown>>, asked: Conversation): Promise<void>;
+    /**
+     * What Claw's record holds: the review it holds (null for a merge), or undefined when it is not for this review, or holds
+     * nothing a card can show (a card that names another pull request would be answered as if it were this one).
+     */
+    private heldOf;
+    private sendCard;
+    /** A click on Merge / Do not merge (Post review / Do not post). */
+    click(sender: UserRef, data: Readonly<Record<string, unknown>>, settle: Settle, conversation: Conversation): Promise<void>;
+    /** What follows an answer: the card that connects the person when needed, and the group told how it ended. */
+    private afterAnswer;
+    /** THE answer of the person a held write waits for. `row` is the store's and its owner is `sender` (the caller checked). */
+    answer(row: GithubConfirmation, sender: UserRef, decision: "allow" | "deny", typed: boolean): Promise<Answered>;
+    private decide;
+    private decided;
+    /**
+     * A 1:1 message that answers, in the person's own words, what waits for them: held writes (by number, or all), or the
+     * confirmation setting. It decides exactly as a press does. True when the message was one (handled).
+     */
+    typed(sender: UserRef, text: string, conversation: Conversation): Promise<boolean>;
+    private typedDecisions;
+    /** The model's word on whether a 1:1 message answers what waits for the person: 'answer', 'none', or undefined. */
+    private readAnswer;
+}