@primusclaw/personal-agent 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,65 @@
+import { type GithubState } from "../../ports/github.js";
+import type { Conversation, InboundMessage, UserRef } from "../../ports/surface.js";
+import type { PullRef } from "../../claw/model.js";
+import type { ReviewAsk } from "../request-parse.js";
+import { type ReviewTurn } from "../review-turn.js";
+import type { ReviewDeps, ReviewTaskSlots } from "./deps.js";
+import type { ReviewItems } from "./items.js";
+import type { Notices } from "./notices.js";
+import type { Actor, ReviewerReader } from "./reviewer.js";
+/** Where and by whom a request was made. */
+export interface RequestContext {
+    readonly message: InboundMessage;
+    readonly sender: UserRef;
+    readonly conversation: Conversation;
+    readonly scope: string;
+    /** What the person wrote (the asker's note to the reviewer). */
+    readonly text: string;
+    readonly group: boolean;
+}
+/** What `take` settled, for the start: who asks and for whom, with what. */
+export interface Settled {
+    readonly ctx: RequestContext;
+    readonly ask: ReviewAsk;
+    readonly token: string;
+    readonly modelKey: string;
+    readonly requester: Actor;
+    readonly actor: Actor;
+    readonly state: GithubState;
+    readonly model: string;
+    readonly actingToken: string;
+    readonly actingKey: string;
+    readonly reviews: ReviewTurn[];
+    readonly refused: [PullRef, string][];
+    readonly several: boolean;
+    /** Gives back the per-person count of each review given to it that did not start. */
+    readonly giveBack: (notStarted: readonly ReviewTurn[]) => void;
+    readonly slots: ReviewTaskSlots | undefined;
+}
+export type Launch = (settled: Settled, held: PullRef[], handed: PullRef[]) => Promise<void>;
+export declare class ReviewChecks {
+    private readonly deps;
+    private readonly reviewers;
+    private readonly items;
+    private readonly notices;
+    private readonly launch;
+    constructor(deps: ReviewDeps, reviewers: ReviewerReader, items: ReviewItems, notices: Notices, launch: Launch);
+    private say;
+    /** The pull requests' checks, then `take`. `named`: the reviewer, already known (a handoff); undefined: read from the message. */
+    request(ctx: RequestContext, ask: ReviewAsk, named?: Actor): Promise<void>;
+    /** The asker's identity token, or undefined when they were told what to do. */
+    private askerToken;
+    /** Who reviews: the asker (a 1:1 chat that names nobody), the reviewer a handoff named, or the one the message names. */
+    private whoReviews;
+    /** The reviewer's GitHub binding, usable and authorized, or undefined when the asker was told why not. */
+    private reviewerState;
+    /** A review asked of someone else runs on their own token and key: both, or undefined when the asker was told. */
+    private actingCredentials;
+    /** The model the request named, as the key that pays may use it; '' the default; undefined when the asker was told why not. */
+    private modelFor;
+    private take;
+    /** One review per pull request, each counted for the asker; a pull request its reviewer wrote is refused. */
+    private build;
+    /** The task limit, checked before Claw is asked: only the reviews that start now hold a slot. */
+    private admit;
+}

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

@@ -0,0 +1,38 @@
+import type { Conversation } from "../../ports/surface.js";
+import type { GithubOutcome } from "../../turn/github-outcome.js";
+import type { ReviewTurnOptions, ReviewTurnOutcome } from "../../turn/runner.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 { Notices } from "./notices.js";
+import type { Settled } from "./start.js";
+/** Offers what Claw holds for the reviewer after a turn (`confirm.ts`). */
+export type OfferHeld = (review: ReviewTurn, item: Readonly<Record<string, unknown>>, asked: Conversation) => Promise<void>;
+export declare class ReviewTurns {
+    private readonly deps;
+    private readonly notices;
+    private readonly cards;
+    private readonly follows;
+    offerHeld: OfferHeld;
+    /** Starts a review's items again for the reviewer (`launch.ts`), set by the assembly of the service. */
+    retryAsItem: (review: ReviewTurn, s: Settled) => Promise<boolean>;
+    constructor(deps: ReviewDeps, notices: Notices, cards: ItemCards, follows: AskerFollow);
+    /** What the turn engine is given for a review. */
+    options(review: ReviewTurn, modelKey: string): ReviewTurnOptions;
+    /** A result of the review's write tools: the line that says how it came out; a merge made in the review itself is audited. */
+    noteResult(review: ReviewTurn, outcome: GithubOutcome, model: string): string | undefined;
+    /** The `ReviewTurn.asItem` of a review asked of someone else whose session is made here: tried once, never in a loop. */
+    asItemOnce(review: ReviewTurn, s: Settled): () => Promise<boolean>;
+    /** A review of one's own that is an item ended with its turn: its card shows how. */
+    endOwnItemCard(review: ReviewTurn): void;
+    /** The turn has ended: what follows it, by how it ended. */
+    afterTurn(review: ReviewTurn, finalAnswer: string, outcome: ReviewTurnOutcome, asked: Conversation): Promise<void>;
+    /** Held writes go to the reviewer as cards; and the reviewer, who typed nothing, is told what was done as them. */
+    private followUp;
+    private offerPending;
+    /** The reviewer's notice of what was left on GitHub as them: [delivered, why not]. */
+    private tellActor;
+    private noticeZh;
+    private noticeEn;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * A review's one sentence of what the pull request does (`pr_summary`), shown right under its verdict, clipped as Claw's
+ * views clip it (`clipPrSummary`).
+ */
+import { clipPrSummary } from "../claw/requester-view.js";
+export { clipPrSummary };
+export type { Redact } from "../inbound-text/redact.js";
+/** The line that says what a pull request does, under its verdict; '' when there is none. */
+export declare function prSummaryLine(summary: unknown, lang?: "zh" | "en"): string;
+/** `text` (a verdict line, then the link and anything else) with the summary line right under its first line. */
+export declare function withSummaryLine(text: string, summaryLine: string): string;

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

@@ -0,0 +1,91 @@
+/**
+ * The views of the review delegation, as models (no card JSON): the confirmation-setting card, the card a reviewer confirms
+ * a held write on, a review item's card with Stop (and its end), and the GitHub connect card beside a question. The Teams
+ * package renders them (`teams/src/views/review/`).
+ */
+import type { JsonObject } from "../json.js";
+import type { OutMessage, ViewButton } from "../ports/surface.js";
+import type { ReviewMode } from "./review-turn.js";
+export interface ReviewModeView {
+    /** The one in force ('' none yet). */
+    readonly current: ReviewMode | "";
+    /** The one asked for: its button comes first. */
+    readonly suggested: ReviewMode | "";
+    readonly lead: string;
+    /** How to answer by typing, for a person whose clicks may not arrive ('' none). */
+    readonly hint: string;
+    readonly installUrl: string;
+}
+export interface GithubConfirmView {
+    readonly confirmationId: string;
+    readonly repo: string;
+    readonly number: number;
+    readonly title: string;
+    readonly author: string;
+    readonly headSha: string;
+    readonly reasons: readonly string[];
+    readonly checks: string;
+    readonly requester: string;
+    readonly room: string;
+    /** The review Claw holds (its event, its text masked, how many inline comments), or undefined for a merge. */
+    readonly review: HeldReviewView | undefined;
+    readonly model: string;
+    readonly hint: boolean;
+    readonly installUrl: string;
+    /** Where the merge lands ('' not read). */
+    readonly base: string;
+    readonly login: string;
+    readonly lang: "zh" | "en";
+    readonly summary: string;
+}
+export interface HeldReviewView {
+    readonly event: string;
+    readonly body: string;
+    readonly comments: number;
+}
+export interface ReviewItemView {
+    readonly seq: number;
+    readonly pull: string;
+    readonly who: string;
+    readonly reviewOnly: boolean;
+    readonly model: string;
+    readonly cardId: string;
+    readonly lang: "zh" | "en";
+    readonly queued: boolean;
+}
+export interface EndedItemView {
+    /** What the card showed (`PlacedCard.render`, with the review's summary added). */
+    readonly render: JsonObject;
+    readonly ended: string;
+    readonly cardId: string;
+}
+export interface GithubConnectView {
+    readonly code: string;
+    readonly uri: string;
+    readonly minutes: number;
+    readonly question: string;
+    readonly lang: "zh" | "en";
+    readonly cardId: string;
+}
+declare module "../ports/surface.js" {
+    interface ViewMap {
+        reviewMode: ReviewModeView;
+        githubConfirm: GithubConfirmView;
+        reviewItem: ReviewItemView;
+        endedItem: EndedItemView;
+        githubConnect: GithubConnectView;
+    }
+}
+export declare function reviewModeMessage(model: ReviewModeView): OutMessage;
+export declare function githubConfirmMessage(model: GithubConfirmView): OutMessage;
+export declare function reviewItemMessage(model: ReviewItemView): OutMessage;
+export declare function endedItemMessage(model: EndedItemView): OutMessage;
+export declare function githubConnectMessage(model: GithubConnectView): OutMessage;
+/**
+ * Merge / Do not merge (a held review: Post review / Do not post): what the confirmation card's buttons carry. The data is
+ * the same for both kinds, the id and the choice: which kind it is the store knows.
+ */
+export declare function githubConfirmButtons(confirmationId: string, review: boolean, lang?: "zh" | "en"): ViewButton[];
+export declare const TYPED_MODE_HINT = "\u6309\u94AE\u70B9\u4E0D\u4E86\u65F6\uFF0C\u76F4\u63A5\u56DE\u590D\u300C\u786E\u8BA4\u5168\u81EA\u52A8\u300D\u6216\u300C\u786E\u8BA4\u9AD8\u98CE\u9669\u518D\u95EE\u6211\u300D\u5373\u53EF\u3002 / If the buttons do not work, reply \u786E\u8BA4\u5168\u81EA\u52A8 or \u786E\u8BA4\u9AD8\u98CE\u9669\u518D\u95EE\u6211.";
+/** The confirmation settings: [Chinese, English] of each, the first the default. */
+export declare const REVIEW_MODES: Readonly<Record<ReviewMode, readonly [string, string]>>;

package/dist/types/review-text/asks.d.ts

@@ -0,0 +1,13 @@
+/** A model id as a request writes it. */
+export declare const MODEL_ID = "[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,99}";
+/** "model: X" (or 模型：X) anywhere in a text, read as Python's `re.I` pattern (İ and ı fold to i); a new pattern each call. */
+export declare function modelFieldPattern(): RegExp;
+/** Whether the text says "review 合入" (or "review 并合入", ...). */
+export declare function saysReviewAndMerge(text: string): boolean;
+/** The name and the rest of a review-only ask. */
+export interface ReviewOnlyAsk {
+    readonly who: string;
+    readonly rest: string;
+}
+/** "请 XX 帮我 review ..." that names someone and says nothing of merging: its name and the rest. */
+export declare function asksReviewOnly(text: string): ReviewOnlyAsk | undefined;

package/dist/types/review-text/bare-numbers.d.ts

@@ -0,0 +1,29 @@
+/** Whether a word, lower-cased, is a word of the sentence rather than a repository ("pr", "the", "merge", ...). */
+export declare function isNotARepo(word: string): boolean;
+/**
+ * A word written as a repository's name rather than as a word of the sentence ("PrimusClaw", "fleet-tools", "Primus2", not
+ * "my", "this" or "API"): what a name GitHub could not confirm must look like before it is read as one.
+ */
+export declare function looksLikeRepo(name: string): boolean;
+/** Pull requests one place of a message names by number alone. */
+export interface BareGroup {
+    /** Where each number is, in the text it was read from (UTF-16 offsets). */
+    readonly spans: readonly (readonly [number, number])[];
+    readonly numbers: readonly number[];
+    /** The repository word written just before the numbers ('' when none). */
+    readonly repo: string;
+    /** Written after "PR" or "#": a pull request whatever comes before it. */
+    readonly explicit: boolean;
+}
+/**
+ * Every place `text` names pull requests by number alone. Links, owner/repo#N, mentions, tags and HTML entities are not read
+ * (they are blanked first, so the places stay where they are in `text`).
+ */
+export declare function bareGroups(text: string): BareGroup[];
+/**
+ * The numbers `text` writes on their own that none of `groups` holds: in a request to review and merge, each may be a pull
+ * request the asker meant, so it is named back to them rather than dropped without a word.
+ */
+export declare function strayNumbers(text: string, groups: readonly BareGroup[]): number[];
+/** The distinct repositories ("owner/repo") the text names: in its links, its owner/repo#N, and owner/repo written alone. */
+export declare function writtenRepos(text: string): string[];

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

@@ -0,0 +1,10 @@
+/**
+ * Reading a review request's text: the people it names, the pull requests it points at, the numbers written on their
+ * own, and the words of an ask (github_review.py; shared by the review delegation and the assistant's understanding).
+ */
+export * from "./asks.js";
+export * from "./bare-numbers.js";
+export { MAX_CANDIDATES, displayName, markerIndexes, markerKeys, markerPattern, memberKeys, memberMatches, memberNames, mentionId, namedIn, namedWithin, normName, oneLine, personOf, plainText, samePerson, sortedCp, tokens, withoutMarkers, withoutParens, writtenIn, } from "./names.js";
+export type { Mention, Place } from "./names.js";
+export * from "./pull-ref.js";
+export { NAME_PADDING, bareName, casefold, codePoints, flat, isAlnum, isWordChar, stripChars, unique, } from "./text/unicode.js";

package/dist/types/review-text/markers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The markers a mention is replaced with in a message's text (`⟦i⟧` is mentions[i]), so that a name in a mention is
+ * never read as written words. The channel's inbound text (marked text) writes them; the readings here skip them.
+ */
+export declare const MARK_OPEN = "\u27E6";
+export declare const MARK_CLOSE = "\u27E7";

package/dist/types/review-text/names.d.ts

@@ -0,0 +1,60 @@
+import type { InboundMention, RosterMember } from "../ports/surface.js";
+/** One person @mentioned in a message: the channel's id for them, their directory id ('' not given) and display name. */
+export type Mention = Pick<InboundMention, "channelUserId" | "userId" | "name">;
+export declare const MAX_CANDIDATES = 5;
+export declare function markerPattern(): RegExp;
+/** The mention indexes a text's markers name, in order. */
+export declare function markerIndexes(text: string): number[];
+/** The markers' numbers as exact decimal strings (Python's `int` of each), to compare markers of any length. */
+export declare function markerKeys(text: string): string[];
+export declare function withoutMarkers(text: string): string;
+export declare function withoutParens(text: string): string;
+export declare function hasCjk(text: string): boolean;
+/** A display name as a prompt or a message carries it: one line, no markup, at most 60 characters. */
+export declare function displayName(value: string): string;
+/** Text that came from outside as one plain line: no markup, at most `limit` characters. */
+export declare function oneLine(value: unknown, limit: number): string;
+/** A value from outside as text: a string as it is, a number as written, anything else (or nothing) as ''. */
+export declare function plainText(value: unknown): string;
+/** A name compared as words: case and runs of space left out. */
+export declare function normName(name: string): string;
+/** Strings sorted by code point (Python's `sorted`). */
+export declare function sortedCp(values: readonly string[]): string[];
+/**
+ * The words of a text, case left out: split at spaces, punctuation and "_", and where Chinese meets a letter or a digit
+ * ("帮我请linmei" is two words, never one that hides the name).
+ */
+export declare function tokens(text: string): string[];
+/**
+ * The words of `name` stand next to each other in `text`, in any order, or `name` is written run together as one word of
+ * it. Whole words only; a Chinese name runs into the words around it, so one is found inside a word that has Chinese.
+ */
+export declare function writtenIn(name: string, text: string): boolean;
+/** A mention's id: the channel's id for the person, else their directory id, else their name. */
+export declare function mentionId(mention: Mention): string;
+/** Two ways a request names its reviewer (markers of mentions, or typed words) are the same person. */
+export declare function samePerson(a: string, b: string, mentions: readonly Mention[]): boolean;
+/** The reviewer a reading gives is the one the rules' span names: the same person, or written inside that span. */
+export declare function namedWithin(who: string, span: string, mentions: readonly Mention[]): boolean;
+/** Who a reviewer the model wrote is, to tell two people apart: a mention's id (by id or display name), else the name, flat. */
+export declare function personOf(who: string, mentions: readonly Mention[]): string;
+/**
+ * Every way a person's name may be written, flat: the display name with or without its bracketed part, its words in either
+ * order, given name and surname, and the account name of their address with or without its digits.
+ */
+export declare function memberKeys(member: RosterMember): Set<string>;
+/** Positions in a text's words, as "word:letter" keys. */
+export type Place = ReadonlySet<string>;
+/**
+ * Where in a text of these words the member's name is written (empty: nowhere): the words of their display name next to
+ * each other in any order, one word that is a way of writing their name run together (at least 4 letters), or a Chinese
+ * name inside a word with Chinese in it. Letters, not words, so a name inside a longer one is seen to be part of it.
+ */
+export declare function namedIn(words: readonly string[], member: RosterMember): Place;
+/** (the members a typed name is, the members it only resembles). */
+export declare function memberMatches(typed: string, members: readonly RosterMember[]): {
+    readonly hits: RosterMember[];
+    readonly near: RosterMember[];
+};
+/** The names of up to MAX_CANDIDATES members, as they are offered back. */
+export declare function memberNames(members: readonly RosterMember[]): string;

package/dist/types/review-text/pull-ref.d.ts

@@ -0,0 +1,25 @@
+/** A pull request named in a review request, and how one is read out of text (links and owner/repo#N). */
+import type { PullRef } from "../claw/model.js";
+export { MARK_CLOSE, MARK_OPEN } from "./markers.js";
+export type PullKey = string;
+export declare function pullRef(owner: string, repo: string, number: number): PullRef;
+export declare function slug(pull: PullRef): string;
+export declare function shortName(pull: PullRef): string;
+export declare function pullUrl(pull: PullRef): string;
+/** What Claw binds a review session to (`config.review_target`). */
+export declare function pullTarget(pull: PullRef): [string, string, number];
+/** A pull request as GitHub compares it: owner and repository without case. */
+export declare function pullKey(pull: PullRef): PullKey;
+export declare function keyOf(owner: string, repo: string, number: number): PullKey;
+export declare function keyParts(key: PullKey): [string, string, number];
+export declare function samePull(a: PullRef, b: PullRef): boolean;
+export declare const PR_URL_SOURCE = "https?://github\\.com/([A-Za-z0-9][A-Za-z0-9-]{0,38})/([A-Za-z0-9._-]{1,100})/pull/(\\p{Nd}{1,7})(?!\\p{Nd})";
+export declare const PR_SHORT_SOURCE = "(?<![A-Za-z0-9_/.-])([A-Za-z0-9][A-Za-z0-9-]{0,38})/([A-Za-z0-9._-]{1,100})#(\\p{Nd}{1,7})(?!\\p{Nd})";
+export declare function prUrlPattern(): RegExp;
+export declare function prShortPattern(): RegExp;
+/**
+ * The distinct pull requests the text points at, in the order it names them: links and owner/repo#N, mixed, separated by
+ * anything (a comma, 、, a space, a new line).
+ */
+export declare function pullsIn(text: string): PullRef[];
+export declare function withoutGitSuffix(name: string): string;

package/dist/types/review-text/text/scan.d.ts

@@ -0,0 +1,19 @@
+/** One match: where it starts and ends (UTF-16 offsets). */
+export type Span = readonly [number, number];
+/** The spans of an opener, the shortest run to the first closer after it: `[(（][^)）]*[)）]` and `<[^>]*>`. */
+export declare function bracketSpans(text: string, openers: string, closers: string): Span[];
+/** `text` with every span replaced by what `by` gives for its text. */
+export declare function replaceSpans(text: string, spans: readonly Span[], by: (matched: string) => string): string;
+/** `re.sub(r"[(（][^)）]*[)）]", "", text)`. */
+export declare function withoutBracketed(text: string): string;
+/** `path.ext:line` somewhere in the line (`[\w./-]+\.\w{1,8}:\d+`), how a finding is written. */
+export declare function hasFileLine(line: string): boolean;
+/**
+ * The spans of `<[^>]*>|&#?\w+;|https?://\S+|⟦\d+⟧`: leftmost first, the alternatives tried in that order at each place,
+ * non-overlapping.
+ */
+export declare function hiddenSpans(text: string, markOpen: string, markClose: string): Span[];
+/**
+ * The matches of `([A-Za-z][A-Za-z0-9._-]{0,99})#(\d{1,7})(?!\d)`: (the word, the number's digits), leftmost first.
+ */
+export declare function wordHashNumbers(text: string): (readonly [string, string])[];

package/dist/types/review-text/text/unicode.d.ts

@@ -0,0 +1,22 @@
+/** The code points of `text` (Python iterates a string by code point). */
+export declare function codePoints(text: string): string[];
+/** Case left out, as names and repositories are compared. */
+export declare function casefold(text: string): string;
+/** Python's `str.isalnum()` for one character. */
+export declare function isAlnum(ch: string): boolean;
+/** Python's `\w` for one character. */
+export declare function isWordChar(ch: string): boolean;
+/** Every character of `text` that is a letter or a digit, case left out (how a name is compared). */
+export declare function flat(text: string): string;
+/** The distinct values, in the order first seen (Python's `dict.fromkeys`). */
+export declare function unique<T>(values: Iterable<T>): T[];
+/** Python's `str.isupper()`: at least one cased character, and every cased one upper case. */
+export declare function isUpper(text: string): boolean;
+/** Python's `str.strip(chars)`: every character of `chars` taken off both ends. */
+export declare function stripChars(text: string, chars: string): string;
+/** What a name in a request is stripped of: spaces, commas, colons and "@". */
+export declare const NAME_PADDING = " \t,\uFF0C\u3001:\uFF1A@";
+/** `who` with the padding a request leaves around a name taken off ('' when nothing is left). */
+export declare function bareName(who: string): string;
+/** The language of the first text that has anything in it: Chinese when it has Chinese, else English. */
+export declare function pickLang(...texts: readonly string[]): "zh" | "en";

package/dist/types/routing/admission.d.ts

@@ -0,0 +1,83 @@
+import type { Chat } from "./chat.js";
+import type { RouterDeps } from "./deps.js";
+import { KeyedLock } from "./lock.js";
+import type { TurnRegistry } from "./turn-registry.js";
+type AdmissionDeps = Pick<RouterDeps, "limits" | "claw" | "clock" | "logger" | "metrics" | "securityEvent" | "assistant" | "remote">;
+/**
+ * The task slots one review request was given: `granted` pull requests may start, `running` is what the person had when
+ * they asked. A slot is let go when its review turn is kept (it counts as a turn from then on) or when the request is
+ * over; `itemIds` are the work items Claw made for them, which the person's board shows too.
+ */
+export declare class ReviewSlots {
+    private readonly onRelease;
+    readonly userId: string;
+    readonly granted: number;
+    readonly running: number;
+    readonly limit: number;
+    left: number;
+    readonly itemIds: Set<string>;
+    constructor(onRelease: (slots: ReviewSlots) => void, userId: string, granted: number, running: number, limit: number);
+    /** One admitted review was handed to its turn (kept as a turn, or not started at all): its slot is let go. */
+    followed(itemId?: string): void;
+    release(): void;
+}
+/**
+ * The per-person limit on tasks running at the same time (the Python `Agent._running_tasks`, `_count_tasks`,
+ * `_board_count`, `_over_task_limit`, `_admit_reviews`, `_assistant_over_limit`). A task is a chat turn this worker runs,
+ * the attached remote agent's turn, a review admitted or followed, and a work item of the person's assistant in progress
+ * (read from their board, which Claw keeps). What a check admits is registered before the person's lock is let go, so two
+ * messages in two chats cannot both take the last slot.
+ */
+export declare class TaskAdmission {
+    private readonly deps;
+    private readonly turns;
+    private readonly pending;
+    private readonly boardSeen;
+    private readonly boardTaken;
+    private readonly reserved;
+    private readonly reviewSlots;
+    readonly lock: KeyedLock;
+    constructor(deps: AdmissionDeps, turns: TurnRegistry);
+    private now;
+    /** The person's tasks this worker knows of (the board's are added by `count`). */
+    running(userId: string): number;
+    /** The person's messages to the assistant still holding a slot; the expired ones are let go. */
+    handoffsPending(userId: string): number;
+    /** The last message to the assistant was not the assistant's after all (or never reached it): its slot is let go. */
+    dropLastHandoff(userId: string): void;
+    /** The person's tasks running now; the board is read only when that leaves room or a message holds a slot. */
+    count(userId: string, boardKey: string): Promise<number>;
+    /** The review work items the worker counts itself: the board must not count them a second time. */
+    private counted;
+    private readBoard;
+    /**
+     * The person's assistant work items in progress (they run in Claw and count too). Each new item on the board lets go
+     * the slot of the oldest message to the assistant that has not taken one yet.
+     */
+    private boardCount;
+    /**
+     * True (the person is told, and the refusal recorded) when a new task would be one more than they may run. `what`
+     * names the task in the notice; `boardKey` reads their board. Called under the person's lock.
+     */
+    overLimit(chat: Chat, activityId: string, operation: string, what?: string, boardKey?: string): Promise<boolean>;
+    private refused;
+    /**
+     * Admits up to `count` pull requests of one review request before Claw is asked to start them; what is admitted holds
+     * a slot each until its turn is kept or the request is over. Fewer than `count`: the rest is refused (and recorded).
+     */
+    admitReviews(chat: Chat, activityId: string, count: number, boardKey: string): Promise<ReviewSlots>;
+    private forget;
+    /**
+     * A message for the assistant may start a work item, so it is refused while the person is at the limit. One let
+     * through holds a slot until its item is on the board, or for `assistantPendingSeconds`.
+     */
+    assistantOverLimit(chat: Chat, activityId: string, key: string): Promise<boolean>;
+    /**
+     * A remote-agent prompt being sent holds a slot until it counts as running: checked and taken under the person's lock,
+     * so a task admitted next (in another chat) sees it. False: refused (the person was told). The caller lets it go.
+     */
+    admitRemote(chat: Chat, activityId: string, key: string): Promise<boolean>;
+    hold(userId: string): void;
+    letGo(userId: string): void;
+}
+export {};

package/dist/types/routing/chat.d.ts

@@ -0,0 +1,52 @@
+import type { Lang } from "../locales/lang.js";
+import type { Logger } from "../ports/logger.js";
+import type { SettleOptions } from "../ports/routing.js";
+import { type Conversation, type InboundAction, type OutMessage, type UserRef } from "../ports/surface.js";
+import type { RouterStore } from "./deps.js";
+import type { NoteFactory } from "./features.js";
+/**
+ * The language a person is answered in (the Python `Agent._lang_of`): what they said (`/lang`), else the language of
+ * what they last wrote, else, while nothing they wrote has said it, the language of their client (`locale`).
+ */
+export declare function langOf(store: Pick<RouterStore, "prefs">, userId: string, locale: string): Lang;
+/**
+ * The person is answered in the language they write in: one message is enough. A typed command says nothing, nor does a
+ * word of the menu, a link, a name or a word or two (`writtenLang`); after `/lang` nothing they write changes it.
+ */
+export declare function learnLang(store: Pick<RouterStore, "prefs">, userId: string, words: string): void;
+/**
+ * The language help is said in: the person's, unless the words that asked for it are in a language of their own ("你能做什么",
+ * "what can you do") and the person did not choose one (`/lang`).
+ */
+export declare function helpLang(store: Pick<RouterStore, "prefs">, userId: string, locale: string, asked: string | undefined): Lang;
+/** One chat as the router answers in it: who wrote, where to answer, and in which language. */
+export declare class Chat {
+    private readonly store;
+    readonly sender: UserRef;
+    readonly conversation: Conversation;
+    /** "" for the person's 1:1 chat, the conversation id of a group. */
+    readonly scope: string;
+    /** The client's locale of the event being handled ("" for work that runs on its own). */
+    readonly locale: string;
+    constructor(store: Pick<RouterStore, "prefs">, sender: UserRef, conversation: Conversation, 
+    /** "" for the person's 1:1 chat, the conversation id of a group. */
+    scope: string, 
+    /** The client's locale of the event being handled ("" for work that runs on its own). */
+    locale: string);
+    lang(): Lang;
+    zh(): boolean;
+    say(text: string): Promise<void>;
+    sayRich(markdown: string): Promise<void>;
+    send(message: OutMessage): Promise<void>;
+}
+/**
+ * THE way a click ends (the Python `Agent._close_card`): the clicked card is replaced, by `card` or by a note saying it,
+ * and the outcome is said in a new message too, because a phone does not redraw an edited message. A click with no line
+ * (paging, opening a menu: the new card is the outcome) says nothing new. When there is no card to edit, or the edit
+ * failed, the line is said in any case; a failed edit never loses an outcome that was carried out. True when replaced.
+ */
+export declare function settleClick(click: {
+    readonly action: InboundAction;
+    readonly conversation: Conversation;
+    readonly note: NoteFactory;
+}, logger: Logger, card: OutMessage | string, options?: SettleOptions): Promise<boolean>;

package/dist/types/routing/command-table.d.ts

@@ -0,0 +1,32 @@
+import type { InboundMessage } from "../ports/surface.js";
+import type { AccountCommands } from "./commands-account.js";
+import type { SessionCommands } from "./commands-session.js";
+import type { SettingsCommands } from "./commands-settings.js";
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+import type { LinkCommands } from "./link-commands.js";
+export interface CommandSets {
+    readonly settings: SettingsCommands;
+    readonly sessions: SessionCommands;
+    readonly account: AccountCommands;
+    readonly link: LinkCommands;
+}
+/**
+ * The 1:1 chat's commands (the Python `Agent._command`): `text` is carried out when it is one, and true is returned;
+ * false (nothing done) when it is not. `message` is undefined for a command the assistant asked for: the commands that
+ * need the message itself are then not carried out.
+ */
+export declare class CommandTable {
+    private readonly ctx;
+    private readonly sets;
+    constructor(ctx: RouterContext, sets: CommandSets);
+    private route;
+    run(text: string, chat: Chat, key: string, message?: InboundMessage): Promise<boolean>;
+    /** A command a feature carries out (`/brief`, and any other the assembly registered). */
+    private features;
+    private board;
+    private settingsWords;
+    /** `/agents`, `/agent ARGS` (the plural is the one word people remember: `/agents new` is `/agent new`). */
+    private agent;
+    private plain;
+}

package/dist/types/routing/commands-account.d.ts

@@ -0,0 +1,26 @@
+import { type Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+/**
+ * Who the person is to the worker and what it can do for them (the Python `Agent._cmd_help`, `_help_values`,
+ * `_cmd_whoami`, `_github_connections`, `_memory_on`, `_cmd_memory`, `_cmd_memory_switch`, `_cmd_lang`).
+ */
+export declare class AccountCommands {
+    private readonly ctx;
+    constructor(ctx: RouterContext);
+    private memoryPage;
+    /** What the bot can do, by category, each with a sentence to type; not a list of commands. */
+    help(chat: Chat, key: string | undefined, asked: string | undefined): Promise<void>;
+    /** On top of help: where this chat's messages go while it is attached to an agent's session, and how to come back. */
+    private attachedLead;
+    /** The person's settings as help shows them ("当前：..."); what the review service cannot read just now is left out. */
+    private values;
+    /** Whose account this chat is connected to, and what else the person is connected to. */
+    whoami(chat: Chat, key: string): Promise<void>;
+    private githubConnections;
+    private memoryOn;
+    memory(chat: Chat, key: string): Promise<void>;
+    /** `/memory on` / `/memory off`: the person's memory in Claw, switched as them and said as Claw answers. */
+    memorySwitch(chat: Chat, key: string, arg: string): Promise<void>;
+    /** `/lang zh|en` answers in that language from now on; `/lang auto` follows what they write; `/lang` says which. */
+    lang(chat: Chat, arg: string): Promise<void>;
+}

package/dist/types/routing/commands-session.d.ts

@@ -0,0 +1,40 @@
+import type { InboundAction } from "../ports/surface.js";
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+import { type ActiveTurn } from "./turn-registry.js";
+import type { TurnStarter } from "./turn-start.js";
+/**
+ * The chat's session (the Python `Agent._cmd_new`, `_cmd_stop`, `_cmd_sessions`, `_cmd_repo`, `_repo_click`, `_bind_repo`,
+ * `_create_pr`): start over, stop what runs, go back to an earlier session, start the next one in a repository.
+ */
+export declare class SessionCommands {
+    private readonly ctx;
+    private readonly starter;
+    constructor(ctx: RouterContext, starter: TurnStarter);
+    new(chat: Chat, scope?: string): Promise<void>;
+    stop(chat: Chat, key: string, scope?: string): Promise<void>;
+    /**
+     * `/stop` of the turn on the chat's own session (not a remote agent's, not the assistant's). `only`: stop only while that
+     * turn is the one running (a Stop card's turn), checked with no wait before the interrupt goes; false when it is not, and
+     * nothing was said or stopped.
+     */
+    stopTurn(chat: Chat, key: string, scope?: string, only?: ActiveTurn): Promise<boolean>;
+    private interrupt;
+    /**
+     * The five sessions this chat used last, a card each with Show here. No session is shown on the worker's word alone: each
+     * is read from Claw with the person's credential, which answers only for their own; one gone or not theirs is forgotten.
+     */
+    sessions(chat: Chat, key: string): Promise<void>;
+    private readable;
+    /** `/repo owner/name [branch]`, or `/repo` alone for the five picked last (each with a button). */
+    repo(chat: Chat, arg: string): Promise<void>;
+    /** A tap on a repository card. The card is not trusted: its text is read like typed text. */
+    repoClick(action: InboundAction, chat: Chat): Promise<void>;
+    /** The next message starts a new session bound to `pick`; the session in use stays on the /sessions list. */
+    private bindRepo;
+    /**
+     * Create PR under a changes card: the agent is asked, in this chat's session, to open a pull request. The card is not
+     * trusted: its session must be the chat's current one, and the ask is an ordinary message (held for approval as any).
+     */
+    createPr(action: InboundAction, chat: Chat, key: string): Promise<void>;
+}