@primusclaw/personal-agent 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,100 @@
+/**
+ * What the review delegation service is built from: ports (store, Claw, GitHub, the channel, the token exchange, time),
+ * and the hooks of the chat it runs in (the router starts its turns, admits its tasks and onboards people). Nothing here
+ * is a concrete adapter: the assembly passes them, and tests pass fakes.
+ */
+import type { JsonObject } from "../../json.js";
+import type { Guardrails } from "../../guardrails/guardrails.js";
+import type { Lang } from "../../locales/lang.js";
+import type { TokenExchange } from "../../plugins/token-exchange.js";
+import type { ClawPort } from "../../ports/claw/index.js";
+import type { Clock } from "../../ports/clock.js";
+import type { DeviceFlow, GithubCredentials, IntentReader, PullReader } from "../../ports/github.js";
+import type { Logger } from "../../ports/logger.js";
+import type { StorePort } from "../../ports/store/index.js";
+import type { Conversation, ConversationRef, InboundMessage, Surface, UserRef } from "../../ports/surface.js";
+import type { PublicErrors } from "../../public-error/public-errors.js";
+import type { ReviewTurn } from "../review-turn.js";
+import type { ReviewTurnOptions } from "../../turn/runner.js";
+import type { Redact } from "../summary.js";
+/** The per-person limits of the operations that act with someone's authority (W2's `Guardrails`). */
+export type Guard = Pick<Guardrails, "take" | "giveBack">;
+/** The audit trail of what was done with a person's GitHub account (`guardrails.audit`). */
+export type Audit = (event: string, fields: Readonly<Record<string, unknown>>) => void;
+/** The task slots a request's reviews may use (`Agent._admit_reviews`). */
+export interface ReviewTaskSlots {
+    readonly granted: number;
+    readonly running: number;
+    readonly limit: number;
+    /** The Claw items the slots hold (counted once on the asker's board). */
+    readonly itemIds: Set<string>;
+    /** A review is now followed as a turn (or did not start): its slot is let go. */
+    followed(itemId: string): void;
+    release(): void;
+}
+/** A review turn the router started: `ended` settles when the turn has ended, whichever way. */
+export interface StartedReviewTurn {
+    readonly ended: Promise<void>;
+}
+export interface StartReviewTurn {
+    readonly message: InboundMessage;
+    readonly sender: UserRef;
+    /** The asker's exchanged identity token. */
+    readonly token: string;
+    readonly prompt: string;
+    readonly conversation: Conversation;
+    readonly scope: string;
+    readonly review: ReviewTurn;
+    /** The asker's own linked key, the model key of a review of their own ('' none). */
+    readonly modelKey: string;
+    /** What the turn engine is given for a review (`TurnRun.review.turn`). */
+    readonly turn: ReviewTurnOptions;
+}
+/** What the chat the service runs in does for it. */
+export interface ReviewHost {
+    /** Starts the review's turn; undefined when it did not start (the asker was told why). */
+    startTurn(request: StartReviewTurn): Promise<StartedReviewTurn | undefined>;
+    /** The usual onboarding of a group member who is not connected (`identity`: they connect at the identity service). */
+    onboard(message: InboundMessage, sender: UserRef, conversation: Conversation, scope: string): Promise<void>;
+    /** The steps that link a person's own Primus key (`/link`), after `lead`. */
+    askLink(person: UserRef, conversation: Conversation, lead: string): Promise<void>;
+    /** The card that binds a person at the identity service, after `lead`. */
+    connectIdentity(person: UserRef, conversation: Conversation, lead: string): Promise<void>;
+    /** The task slots `count` reviews may use; undefined: no task limit here. */
+    admitReviews?(message: InboundMessage, sender: UserRef, count: number, modelKey: string): Promise<ReviewTaskSlots>;
+    /** '' when what waits for this person reaches their chat (their subscription made or mended first), else why not. */
+    reviewerReach?(userId: string): Promise<string>;
+}
+/** The channel's fields a followed review keeps to reach the reviewer again after a restart (Teams: service url, tenant, bot). */
+export type FollowWire = (asked: ConversationRef) => Readonly<Record<string, string>>;
+/** A conversation reference again, from what the store kept of it (the channel's own reference); undefined when unreadable. */
+export type RestoreRef = (stored: JsonObject) => ConversationRef | undefined;
+export interface ReviewDeps {
+    readonly store: StorePort;
+    readonly claw: ClawPort;
+    readonly credentials: GithubCredentials;
+    readonly device: DeviceFlow;
+    readonly pulls: PullReader;
+    /** undefined: requests are read by the rules alone. */
+    readonly intent: IntentReader | undefined;
+    readonly surface: Surface;
+    readonly exchange: TokenExchange;
+    readonly clock: Clock;
+    readonly logger: Logger;
+    readonly errors: PublicErrors;
+    /** Credential shapes masked: what a group, and a reviewer's own chat, are sent. */
+    readonly mask: Redact;
+    readonly guard: Guard;
+    readonly audit: Audit;
+    readonly host: ReviewHost;
+    readonly followWire: FollowWire;
+    readonly restoreRef: RestoreRef;
+    /** The owners whose public repositories may be reviewed (REVIEW owners). */
+    readonly owners: readonly string[];
+    /** The "Add the app" link on a card for a person who may not have the app ('' none). */
+    readonly installUrl: string;
+    /** What a review runs on when its request names no model ('' Claw's default). */
+    readonly defaultModel: string;
+}
+/** The language of a text a person wrote, as the review service answers in it. */
+export type ReviewLang = Lang;

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

@@ -0,0 +1,53 @@
+import { type Conversation } from "../../ports/surface.js";
+import { type ReviewTurn } from "../review-turn.js";
+import type { ReviewDeps } from "./deps.js";
+import type { ItemCards } from "./item-cards.js";
+import type { Notices } from "./notices.js";
+/** How often the asker's view of a review someone else runs is read. */
+export declare const REQUESTER_VIEW_MS = 30000;
+export declare const REQUESTER_VIEW_LIMIT_SECONDS: number;
+/** News is held this long for more to join it, at most this long in all. */
+export declare const VIEW_SETTLE_MS = 90000;
+export declare const VIEW_HOLD_MS = 600000;
+/** How often a last line is tried before it is left (to the next worker that starts). */
+export declare const DEADLINE_TRIES = 10;
+export declare class AskerFollow {
+    private readonly deps;
+    private readonly cards;
+    private readonly notices;
+    /** item id -> the follow of its request. */
+    private readonly viewing;
+    /** Items the asker stopped from their card: their end is said there, not again. */
+    private readonly stopped;
+    /** For tests: the interval between reads. */
+    viewMs: number;
+    constructor(deps: ReviewDeps, cards: ItemCards, notices: Notices);
+    following(itemId: string): boolean;
+    /** Settles when every follow started so far has ended. */
+    idle(): Promise<void>;
+    /** Whether the asker stopped this item from its card (forgotten once asked). */
+    takeStopped(itemId: string): boolean;
+    /** The asker stopped the item from their card, where that is said: its end is not said a second time. */
+    itemStopped(itemId: string): void;
+    /** Follows the reviews one request asked of someone else, together, for their asker. */
+    follow(reviews: readonly ReviewTurn[], conversation: Conversation): void;
+    private start;
+    /** Every review that was followed when the last worker stopped is followed again, from what its asker was told last. */
+    resume(): number;
+    /** Reads each open item's view every `viewMs`; news is held a little, then said in one message. */
+    private watch;
+    private tryFlush;
+    /** The deadline: what is held is said, then that the rest is still open; the rows go once the asker has been told. */
+    private atDeadline;
+    /** The asker's view of one item now; undefined when it is not followed any more, "running" for a moment's trouble. */
+    private viewOf;
+    private round;
+    /** An item the asker stopped on its card: that card is left as the press made it, and said there. */
+    private endStopped;
+    /** What one view is: news to hold, back to what was said, a start, or an end. */
+    private note;
+    /** Says the held news in one message; what is said is recorded first, and put back when the message did not go. */
+    private flush;
+    /** A line for the asker where they asked: in a group it @mentions them (and only them). */
+    sayToAsker(review: ReviewTurn, conversation: Conversation, text: string): Promise<void>;
+}

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

@@ -0,0 +1,72 @@
+import type { Lang } from "../../locales/lang.js";
+import type { JsonObject } from "../../json.js";
+import type { GithubState } from "../../ports/github.js";
+import type { Random } from "../../ports/random.js";
+import type { MessageRoute, RouteHandlers } from "../../ports/routing.js";
+import type { Conversation, InboundMessage, UserRef } from "../../ports/surface.js";
+import type { ReviewTurnOptions, ReviewTurnOutcome } from "../../turn/runner.js";
+import { UNKNOWN } from "../connect/connections.js";
+import { GithubConnect, type ConnectRequest } from "../connect/github-connect.js";
+import type { ReviewHandoff } from "../handoff.js";
+import { type ReviewTurn } from "../review-turn.js";
+import { GithubAccount } from "./account.js";
+import type { ReviewDeps } from "./deps.js";
+import { type PostWorkCard } from "./notices.js";
+export declare class GithubReview {
+    private readonly deps;
+    readonly account: GithubAccount;
+    readonly connect: GithubConnect;
+    private readonly reviewers;
+    private readonly requests;
+    private readonly notices;
+    private readonly cards;
+    private readonly follows;
+    private readonly items;
+    private readonly turns;
+    private readonly held;
+    private readonly checks;
+    private readonly launch;
+    constructor(deps: ReviewDeps, random: Random, postWorkCard: PostWorkCard);
+    /** Settles when the background work started so far (device flows, follows, hints) has ended. For tests. */
+    idle(): Promise<void>;
+    /** Which channel id is whose, from a message of theirs: a mention in a group can then be read without the member list. */
+    remember(message: InboundMessage): void;
+    private context;
+    /**
+     * A message that may be "请 XX 帮我 review 合入 <PR> [<PR> ...]". True when it was one (answered here, or started), false
+     * for any other message. Whoever is named is the only account that is ever used: no one stands in for them.
+     */
+    request(route: MessageRoute): Promise<boolean>;
+    /**
+     * A review the person's assistant handed back: started exactly as the same request typed here is, as the reviewer, with
+     * the reviewer's own exchanged token and linked key, and answered in `conversation`.
+     */
+    handoff(message: InboundMessage, sender: UserRef, conversation: Conversation, handoff: ReviewHandoff): Promise<void>;
+    /** A 1:1 message that asks, in the person's own words, to change or see the confirmation setting. True when it was one. */
+    modeMessage(sender: UserRef, text: string, conversation: Conversation): Promise<boolean>;
+    /** What the turn engine is given for a review. */
+    turnOptions(review: ReviewTurn, modelKey: string): ReviewTurnOptions;
+    /** A review's turn has ended (the router calls this with what the engine collected). */
+    afterTurn(review: ReviewTurn, finalAnswer: string, outcome: ReviewTurnOutcome, asked: Conversation): Promise<void>;
+    /** The asker stopped an item from its card, where that is said. */
+    itemStopped(itemId: string): void;
+    /** Called once the worker runs: the follows of the last worker are taken up again. */
+    resume(): number;
+    /** Open review cards are checked for an item that is over, now and then every CARD_SWEEP_MS, until `signal` aborts. */
+    sweepCards(signal: AbortSignal): Promise<void>;
+    /** The open confirmations of the person (the assistant's context). */
+    pendingConfirmations(userId: string): readonly JsonObject[];
+    /** Beside a question about the person's own GitHub: the connect card, before the question goes on (`GithubConnect.offer`). */
+    offerConnect(request: ConnectRequest): Promise<void>;
+    /**
+     * The person's GitHub binding at the identity service, as /whoami shows it (Python `Agent._github_connections`): their
+     * state, null when they have none, UNKNOWN when the identity service could not say just now (never "not connected").
+     */
+    connectionState(userId: string): Promise<GithubState | null | typeof UNKNOWN>;
+    /** Help's values of the person's GitHub ("github", "delegation", "confirm_mode"); those it cannot read are left out. */
+    helpValues(userId: string, lang: Lang): Promise<Readonly<Record<string, string>>>;
+    private within;
+    /** What the review delegation brings the router. */
+    routeHandlers(): RouteHandlers;
+    private click;
+}

package/dist/types/review/service/handoff-action.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A review the person's assistant handed back (`review_for_other`, an `assistant.action` with a typed `review`): the assistant
+ * understood the message, and the review runs on the reviewer's own credentials, which only this worker holds (teams_agent/agent.py
+ * `_review_handoff`, `_run_handoff`). It is started exactly as the same request typed here would be, only for a message this worker
+ * sent for this person that declared the handoff, only of someone that message named, and once per event id. It runs in the
+ * background (a review's checks outlast a delivery) and answers in one message: the assistant says nothing about it, so the answer
+ * closes the receipt under the person's message when that is still open.
+ */
+import { type Receipts } from "../../assistant/receipts.js";
+import type { ReviewDeps } from "./deps.js";
+import type { GithubReview } from "./github-review.js";
+export interface HandoffActionDeps {
+    readonly review: Pick<GithubReview, "handoff">;
+    readonly receipts: Receipts;
+    /** The assistant understands the person's messages. */
+    readonly understands: (userId: string) => boolean;
+    /** The person's assistant can answer them. */
+    readonly reachable: (userId: string) => boolean;
+}
+type Event = Readonly<Record<string, unknown>>;
+export declare class ReviewHandoffAction {
+    private readonly deps;
+    private readonly action;
+    private readonly running;
+    constructor(deps: ReviewDeps, action: HandoffActionDeps);
+    /** Settles when every handoff taken so far has run. For tests. */
+    idle(): Promise<void>;
+    /** The handoff `event` for `userId`, taken and started in the background ('delivered'), or 'dropped'. */
+    take(userId: string, event: Event): "delivered" | "dropped";
+    private run;
+}
+export {};

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

@@ -0,0 +1,27 @@
+import type { GithubConnection } from "../../claw/model.js";
+import { type ReviewMode } from "../review-turn.js";
+import type { ReviewDeps } from "./deps.js";
+/** Claw answers 404 for the setting: its API is not deployed yet, and every review is confirmed as by default. */
+export declare const NOT_YET = "not_yet";
+export type ModeRead = ReviewMode | typeof NOT_YET | "";
+/** The exchanged token that acts as `userId`, or why there is none. */
+export declare function tokenFor(deps: ReviewDeps, userId: string): Promise<{
+    readonly token: string;
+} | {
+    readonly failed: "not_bound" | "unavailable";
+    readonly reason: string;
+}>;
+/** A failed call of Claw's (an answer, no answer, an answer not understood); anything else is a bug and is thrown on. */
+export declare function clawFailure(err: unknown): boolean;
+/**
+ * The person's confirmation setting as Claw holds it, read as them; '' when it cannot be read, NOT_YET for a Claw without
+ * it. A value this worker does not know is the default, as Claw itself reads it.
+ */
+export declare function modeOf(deps: ReviewDeps, userId: string): Promise<ModeRead>;
+/** Writes the person's confirmation setting as them: true, NOT_YET for a Claw without it, false when it was not written. */
+export declare function writeMode(deps: ReviewDeps, userId: string, mode: ReviewMode): Promise<true | false | typeof NOT_YET>;
+/**
+ * What Claw says about the person's GitHub tools, asked as them, and whether it could say: [null, true] for a Claw without
+ * the answer, [null, false] when it could not be asked.
+ */
+export declare function connectionOf(deps: ReviewDeps, userId: string): Promise<readonly [GithubConnection | null, boolean]>;

package/dist/types/review/service/item-cards.d.ts

@@ -0,0 +1,39 @@
+import type { PlacedCard } from "../../ports/store/assistant.js";
+import type { Conversation } from "../../ports/surface.js";
+import { type ReviewTurn } from "../review-turn.js";
+import type { ReviewDeps } from "./deps.js";
+/** The plain end a card gets when Teams refused the full one. */
+export declare const ITEM_CARD_ENDED_PLAIN_ZH = "\u5DF2\u7ED3\u675F\uFF0C\u89C1\u4E0A\u65B9\u7ED3\u679C";
+/** Open review cards are checked this often for an item that is over. */
+export declare const CARD_SWEEP_MS = 120000;
+/** ... posted within this long (all the store keeps: a review held for its reviewer may end late). */
+export declare const CARD_SWEEP_MAX_AGE_SECONDS: number;
+export declare class ItemCards {
+    private readonly deps;
+    /** Item ids whose end is said by a follow here (their cards are not swept). */
+    private readonly followed;
+    /** item id -> where its card with Stop was sent. */
+    private readonly cardAt;
+    /** item id -> how it ended (and the review's summary), for an item that ended before its card went out. */
+    private readonly endedBeforeCard;
+    constructor(deps: ReviewDeps, 
+    /** Item ids whose end is said by a follow here (their cards are not swept). */
+    followed: (itemId: string) => boolean);
+    has(itemId: string): boolean;
+    forget(itemId: string): void;
+    /** A card for each review item in `target` (the asker's own chat). Best effort: an item without a card stays on the board. */
+    post(target: Conversation, ownerId: string, reviews: readonly ReviewTurn[], shownModel: (r: ReviewTurn) => string): Promise<void>;
+    /** A review that waited for a slot has started: each open card that still says it is queued becomes the running card. */
+    started(itemId: string): Promise<void>;
+    /** The review item ended: every card of it still open shows how, in place of its buttons. */
+    end(itemId: string, ended: string, prSummary?: string): Promise<void>;
+    /** Edits one open card into its end; a plain end when the channel refuses the full one. False when this call did not end it. */
+    close(card: PlacedCard, ended: string, prSummary?: string): Promise<boolean>;
+    /** How the item of one open card ended, read as the card's owner; undefined while it runs or when it cannot be read now. */
+    private endOf;
+    /**
+     * Every open card of a review item posted within `maxAge`, whose item is over, is edited into its end: what a follow did
+     * not end is ended here. Returns how many cards it ended.
+     */
+    closeEnded(maxAge?: number): Promise<number>;
+}

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

@@ -0,0 +1,57 @@
+import type { PullRef } from "../../claw/model.js";
+import type { ReviewTurn } from "../review-turn.js";
+import type { ReviewDeps } from "./deps.js";
+import type { Actor } from "./reviewer.js";
+/** How long Claw's answer to whether it chooses a review's model is reused. */
+export declare const CLAW_MODELS_MS = 300000;
+/** What asking for the items came to. */
+export type ItemsAsked = {
+    readonly kind: "started";
+    readonly reviews: ReviewTurn[];
+}
+/** A Claw without review items: the sessions are made here. */
+ | {
+    readonly kind: "no_items";
+}
+/** Claw started none, or could not be asked: what the asker is told. */
+ | {
+    readonly kind: "refused";
+    readonly text: string;
+};
+export interface ItemsRequest {
+    readonly token: string;
+    readonly modelKey: string;
+    readonly actor: Actor;
+    readonly actingAs: string;
+    readonly merge: boolean;
+    readonly model: string;
+    /** Asked of someone else: their exchanged token and own key ('' a review of one's own). */
+    readonly actingToken: string;
+    readonly actingKey: string;
+    /** The asker's own words, quoted to the reviewer as untrusted. */
+    readonly note: string;
+    readonly handoffId: string;
+}
+export declare class ReviewItems {
+    private readonly deps;
+    private clawModels;
+    /** The pull requests a review was asked for and has not ended (a Claw without review items: this worker's memory). */
+    private readonly reviewing;
+    constructor(deps: ReviewDeps);
+    /** Whether Claw chooses a review's model itself, asked at most every CLAW_MODELS_MS; the last answer stands when it cannot say. */
+    clawChoosesModels(token: string): Promise<boolean>;
+    /** Asks Claw for one item per review; see `ItemsAsked`. Refused pull requests go in `refused`. */
+    start(request: ItemsRequest, reviews: readonly ReviewTurn[], refused: [PullRef, string][]): Promise<ItemsAsked>;
+    private ask;
+    /** What a refusal leaves: the reviews to ask for again, no items here, or the one line for the asker. */
+    private afterRefusal;
+    private checkReason;
+    private taken;
+    /**
+     * A Claw without review items: the pull requests this worker is reviewing already are refused, and the others are taken
+     * (in `held`) until their review ends. This worker's memory is all there is then.
+     */
+    hold(reviews: readonly ReviewTurn[], refused: [PullRef, string][], held: PullRef[]): ReviewTurn[];
+    /** A review taken in this worker's memory has ended (or never started): its pull request is free again. */
+    release(pull: PullRef): void;
+}

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

@@ -0,0 +1,37 @@
+import type { PullRef } from "../../claw/model.js";
+import { type ReviewTurn } from "../review-turn.js";
+import type { ReviewDeps } from "./deps.js";
+import type { AskerFollow } from "./follow.js";
+import type { ItemCards } from "./item-cards.js";
+import type { ReviewItems } from "./items.js";
+import type { Notices } from "./notices.js";
+import type { Settled } from "./start.js";
+import type { ReviewTurns } from "./turns.js";
+export declare class ReviewLaunch {
+    private readonly deps;
+    private readonly items;
+    private readonly notices;
+    private readonly cards;
+    private readonly follows;
+    private readonly turns;
+    constructor(deps: ReviewDeps, items: ReviewItems, notices: Notices, cards: ItemCards, follows: AskerFollow, turns: ReviewTurns);
+    /** The model a review's card and receipt name: the one Claw says it runs on, else the one asked for (or the default). */
+    shownModel(review: ReviewTurn): string;
+    launch(s: Settled, held: PullRef[], handed: PullRef[]): Promise<void>;
+    /** Claw's items for the reviews (or the reviews this worker takes itself); undefined when the asker was told why not. */
+    private startItems;
+    private nothingStarted;
+    /** The acknowledgement: one message for several reviews, else at the top of the review's progress message. */
+    private acknowledge;
+    private severalText;
+    /** A turn for each review of one's own; the asker follows the reviews asked of someone else together. */
+    private run;
+    private startTurn;
+    /**
+     * A review asked of someone else whose session was made here, refused by a newer Claw (`acting_as_must_be_self`): asked for
+     * once more as the reviewer's item, exactly as the start asks. True: the asker was told; false: the turn says its failure.
+     */
+    asItem(review: ReviewTurn, s: Settled): Promise<boolean>;
+    /** The cards with Stop, in the asker's own chat (a group's request too). */
+    postCards(s: Settled, reviews: readonly ReviewTurn[]): Promise<void>;
+}

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

@@ -0,0 +1,42 @@
+import type { WorkItem, PullRef } from "../../claw/model.js";
+import type { Conversation, ConversationRef, UserRef } from "../../ports/surface.js";
+import { type ReviewTurn } from "../review-turn.js";
+import type { ReviewDeps } from "./deps.js";
+import type { Actor } from "./reviewer.js";
+/** A person who was named but has not bound GitHub (or the asker who has not linked) is told how at most once a day. */
+export declare const BIND_NOTICE_SECONDS: number;
+/** Puts a card of a work item in a chat and keeps where it went (the assistant's work card; owned by the assistant line). */
+export type PostWorkCard = (conversation: Conversation, owner: string, item: WorkItem, text: string) => Promise<void>;
+export declare class Notices {
+    private readonly deps;
+    private readonly postWorkCard;
+    constructor(deps: ReviewDeps, postWorkCard: PostWorkCard);
+    /** The asker's exchanged token, to read what a review's session holds as them; undefined when there is none now. */
+    requesterToken(review: ReviewTurn): Promise<string | undefined>;
+    /**
+     * Claw did not take the asker's credentials for this review (401): what they can do goes to them alone. A key that belongs
+     * to another Primus account than the one connected at the identity service (`key_subject_mismatch`) is linked again from
+     * the right account; any other is linked again.
+     */
+    tellRequesterRefused(review: ReviewTurn, code: string): Promise<void>;
+    /** A person's own 1:1 chat. */
+    personalChatOf(person: Actor, via: ConversationRef): Promise<Conversation | undefined>;
+    /** The reviewer's own 1:1 chat. */
+    reviewerChat(review: ReviewTurn): Promise<Conversation | undefined>;
+    tellReviewer(review: ReviewTurn, text: string): Promise<void>;
+    /** The reviewer hears, in their own chat, that someone asked a review of them and that it is an item on their board. */
+    tellReviewerStarted(review: ReviewTurn): Promise<void>;
+    /** The reviewer's item as Claw shows it to them, read with their own key; undefined when it cannot be. */
+    private reviewersItem;
+    /** The reviewer's item waits for them: what it asks and how to answer, with the item's card when it can be read as them. */
+    tellReviewerWaiting(review: ReviewTurn, prSummary: string): Promise<void>;
+    private waitingText;
+    /** For a review handed to someone else: '' when what waits for them reaches their chat, else one line for the asker. */
+    reachNote(review: ReviewTurn | undefined): Promise<string>;
+    /** Sends what `send` says into the person's own chat, at most once a day for this kind; true when they have it. */
+    onceADay(person: Actor, via: ConversationRef, kind: string, send: (chat: Conversation) => Promise<void>): Promise<boolean>;
+    /** The asker has no Primus key of their own linked, and a review runs on it: one line where asked, and the steps in their chat. */
+    requesterMustLink(via: ConversationRef, group: boolean, requester: Actor, conversation: Conversation, pulls: readonly PullRef[]): Promise<void>;
+    /** The person named cannot be acted as yet: one line where asked and, once a day, the steps in their own chat. */
+    noGithub(via: ConversationRef, group: boolean, sender: UserRef, actor: Actor, pulls: readonly PullRef[], conversation: Conversation, known: boolean): Promise<void>;
+}

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

@@ -0,0 +1,58 @@
+import type { InboundMessage, UserRef } from "../../ports/surface.js";
+import { type PullKey } from "../../review-text/pull-ref.js";
+import { type ReviewAsk } from "../request-parse.js";
+import type { ReviewDeps } from "./deps.js";
+/** A message as the request is read from it. */
+export interface Asking {
+    readonly message: InboundMessage;
+    readonly sender: UserRef;
+    readonly group: boolean;
+}
+/** The message with each bare number written as owner/repo#N, the repository read, and what was and was not taken. */
+export interface Expanded {
+    readonly message: InboundMessage;
+    readonly repo: string;
+    readonly taken: readonly PullKey[];
+    readonly stray: readonly number[];
+}
+/** What reading a request came to: not one (chat), a question asked back, or the request. */
+export type Reading = {
+    readonly kind: "chat";
+} | {
+    readonly kind: "question";
+    readonly text: string;
+} | {
+    readonly kind: "ask";
+    readonly ask: ReviewAsk;
+};
+export declare class RequestReader {
+    private readonly deps;
+    /** A repository name GitHub answered for (lower case) -> its "owner/name". */
+    private readonly reposSeen;
+    constructor(deps: ReviewDeps);
+    private marked;
+    /**
+     * A request that names pull requests by number alone: the message with each number as owner/repo#N, and the repository
+     * it was read as: the one written just before the numbers; the one other repository the message names; the asker's most
+     * recent /repo of an allowed owner. Otherwise one question back: the repository is never guessed.
+     */
+    barePulls(asking: Asking): Promise<Expanded | string>;
+    private recentRepo;
+    private chooseRepos;
+    /**
+     * The one "owner/name" among the allowed owners that GitHub has a public repository `name` for; '' when none or more
+     * than one has; undefined when GitHub could not be asked. With one allowed owner, a GitHub that cannot be asked leaves only
+     * one repository a name that looks like one can be: that owner's (Claw's own read of the pull request refuses a wrong one).
+     */
+    private repoNamed;
+    /**
+     * What the message asks: the model's reading held to the message, when the message names a pull request and the asker
+     * has a key to read it with; else, or when the model gives no reading in time, the rules'.
+     */
+    read(asking: Asking): Promise<Reading>;
+    /**
+     * Every "请 X ..." line must name the reviewer too; and whether it merges is what the words say, never only the model's
+     * reading. A reading that names nobody, or someone else, where the rules read a name is a question, never a guess.
+     */
+    private heldToRules;
+}

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

@@ -0,0 +1,48 @@
+import type { ConversationRef, RosterMember } from "../../ports/surface.js";
+import type { ReviewAsk } from "../request-parse.js";
+import type { ReviewDeps } from "./deps.js";
+/** A group's member list is read again after this long (names are matched against it). */
+export declare const ROSTER_CACHE_MS = 300000;
+/** The member list is given up on after this long. */
+export declare const ROSTER_MS = 10000;
+/** The person a request names. */
+export interface Actor {
+    readonly userId: string;
+    readonly name: string;
+    readonly channelUserId: string;
+}
+/** Who was named could not be settled; `text` is what the asker is told. */
+export interface ActorUnknown {
+    readonly unknown: string;
+}
+/** Where the request was asked, as the roster reads it. */
+export interface Asked {
+    readonly conversation: ConversationRef;
+    readonly group: boolean;
+}
+export declare class ReviewerReader {
+    private readonly deps;
+    /** group conversation id -> (when read, its members). */
+    private readonly rosters;
+    constructor(deps: ReviewDeps);
+    /**
+     * The members of the group chat, or undefined when the channel cannot read them. In a 1:1 chat, which has no group,
+     * everyone the worker has seen write to it.
+     */
+    roster(asked: Asked): Promise<readonly RosterMember[] | undefined>;
+    /** Who the request names, or the question to ask back. */
+    resolve(asked: Asked, ask: ReviewAsk): Promise<Actor | ActorUnknown>;
+    private mentioned;
+    private typed;
+    /**
+     * (channel id -> name of everyone the message may name, how many people it names). Everyone it mentions is one, and so
+     * is every member whose name it writes as words of its own; members found at the very same words are one name written
+     * (one that fits several people: the reviewer's own check asks which), and a member also mentioned is that mention.
+     */
+    peopleNamed(asked: Asked, markedText: string, ask: ReviewAsk): Promise<{
+        people: Map<string, string>;
+        count: number;
+    }>;
+    /** The names of the people a message names, as the asker is told them. */
+    static namesOf(people: ReadonlyMap<string, string>): string;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * A review's turn as the router starts it (`StartTurn.review`): the review service's `ReviewHost.startTurn` on the router's
+ * own `startTurn`, so the worker's assembly only injects the router and the chat it builds. As Python's `_guarded` does for a
+ * review: the session is the review's (never the chat's stored one), it is noted as an acting session as soon as it exists,
+ * and the review service reads the turn once it is over.
+ */
+import type { Chat } from "../../routing/chat.js";
+import type { ReviewTurnStart, RunningTurn, StartTurn } from "../../routing/turn-start.js";
+import type { ReviewTurnOutcome } from "../../turn/runner.js";
+import type { Conversation } from "../../ports/surface.js";
+import type { ReviewTurn } from "../review-turn.js";
+import type { ReviewDeps, ReviewHost, StartReviewTurn } from "./deps.js";
+/** What follows a review's turn (`GithubReview.afterTurn`). */
+export type AfterReviewTurn = (review: ReviewTurn, finalAnswer: string, outcome: ReviewTurnOutcome, asked: Conversation) => Promise<void>;
+/** The router's `startTurn`. */
+export type StartRouterTurn = (request: StartTurn) => Promise<RunningTurn | undefined>;
+/** The review part of the router's `StartTurn` for one review's turn. */
+export declare function reviewTurnStart(request: StartReviewTurn, store: Pick<ReviewDeps["store"], "reviewDelegation">, afterTurn: AfterReviewTurn): ReviewTurnStart;
+/** `ReviewHost.startTurn` on the router's `startTurn`, with the chat `chatOf` builds for the request. */
+export declare function routedReviewTurns(start: StartRouterTurn, chatOf: (request: StartReviewTurn) => Chat, store: Pick<ReviewDeps["store"], "reviewDelegation">, afterTurn: AfterReviewTurn): ReviewHost["startTurn"];