@primusclaw/personal-agent 0.5.0 → 0.7.0

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

@@ -89,6 +89,8 @@ export declare class AssistantChat {
     forget(userId: string): void;
     /** What a message of files and no words says to the assistant. */
     filesOnly(lang: Lang): string;
+    /** The language the person chose to be answered in, as the message's `channel_context` carries it (none: nothing is sent). */
+    private chosenLanguage;
     private langOf;
     /**
      * A message of a person the assistant understands, with the chat's context. True when the assistant has it; otherwise the

package/dist/types/assistant/choice-clicks.d.ts

@@ -0,0 +1,35 @@
+import type { ClickHandler, ClickRoute } from "../ports/routing.js";
+import type { ChoiceCard } from "../ports/store/assistant.js";
+import type { StorePort } from "../ports/store/index.js";
+import type { Logger } from "../ports/logger.js";
+import type { InboundMessage } from "../ports/surface.js";
+export declare const CHOICE_VERB = "assistant_choice";
+/** The id of a choice card's input, whose value is the picked options' places on the card ("0", "0,2"). */
+export declare const CHOICE_INPUT = "choice";
+export interface ChoiceClickDeps {
+    readonly store: Pick<StorePort, "assistantButtons">;
+    /** Handles `message` as the router handles one the person typed (`Router.handle`); throws when it was not handled. */
+    readonly deliver: (message: InboundMessage) => Promise<void>;
+    readonly logger: Logger;
+}
+/** The options `value` picks on `card` (each named by its place), in the card's order; a place it never had is no pick. */
+export declare function pickedOn(card: Pick<ChoiceCard, "options">, value: unknown): string[];
+/**
+ * The message a press sends: the presser's, in the chat it was pressed in, saying `text`, as a typed one is (to the bot, in a
+ * group), but marked `choice`, so no word of it is read as a command.
+ */
+export declare function typedMessage(click: Pick<ClickRoute, "action" | "sender">, text: string, id: string): InboundMessage;
+export declare class AssistantChoiceClicks implements ClickHandler {
+    private readonly deps;
+    readonly verbs: readonly ["assistant_choice"];
+    constructor(deps: ChoiceClickDeps);
+    /** A 1:1 chat: answered with no Claw key (the message it sends is checked as any typed one is). */
+    beforeCredential(click: ClickRoute): Promise<boolean>;
+    inGroup(click: ClickRoute): Promise<boolean>;
+    press(click: ClickRoute): Promise<void>;
+    /** The card back, open, with `note` under its options. */
+    private again;
+    /** The card replaced by what was picked and sent (said as a line too when `announce`). */
+    private sent;
+    private model;
+}

package/dist/types/assistant/events.d.ts

@@ -41,6 +41,23 @@ export declare function confirmWriteOf(event: Event): ConfirmWrite | undefined;
  * line that is no command, else the defaults in the person's language (`lang`; without it, the language of `text`).
  */
 export declare function suggestedRepliesOf(event: Event, text: string, styleOn: boolean, lang?: Lang): SuggestedReply[];
+/** The fewest options a choice card shows (Claw sends from 2). */
+export declare const CHOICE_OPTIONS_MIN = 2;
+/** The most options a choice card shows (Claw sends at most 10). */
+export declare const CHOICE_OPTIONS_MAX = 10;
+/** Code points of one option (Claw sends at most 80): one line beside a radio button or a check box. */
+export declare const CHOICE_OPTION_MAX = 80;
+/** A choice an `assistant.say` puts to the person: the options, and whether several may be picked. */
+export interface SayChoice {
+    readonly options: readonly string[];
+    readonly multiple: boolean;
+}
+/**
+ * The choice an `assistant.say` puts to the person (`choices`); undefined when it carries none this worker draws. Read whole or not
+ * at all: an option that is not one plain line of text, or too many or too few of them, and there is no card (the words still name
+ * the options, for the person to type).
+ */
+export declare function choiceOf(event: Event): SayChoice | undefined;
 export interface RemoteNotice {
     /** `resolved`: a question a terminal asked no longer waits here (answered there, or given up); `resolved` says which. */
     readonly kind: "done" | "needs_you" | "error" | "resolved";

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

@@ -1,6 +1,7 @@
 /** What the assembly wires of the assistant (one line each; the views and work-item text are exported from the package root). */
 export { AssistantActionClicks } from "./action-handler.js";
 export { AssistantActions } from "./actions.js";
+export { AssistantChoiceClicks } from "./choice-clicks.js";
 export { Board } from "./board.js";
 export { AssistantChat as AssistantChatService } from "./chat.js";
 export type { AssistantChatOptions } from "./chat.js";

package/dist/types/assistant/say.d.ts

@@ -5,8 +5,9 @@
  *   receipt already shows of it (`shown`). It is an AI answer: the AI label and the thumbs under it, a citation for each source it
  *   cites as [n], and the replies to tap under the last of its messages when no card follows.
  * - When the event's item holds a result that waits, a card with Accept and Stop; when it holds a write for the person, a card
- *   that lets it through or not; when it puts a command to the person, a card with Run and Cancel (each recorded first, so its
- *   buttons mean something). A card holds the words only when they are short and not shown already.
+ *   that lets it through or not; when it puts a command to the person, a card with Run and Cancel; when it puts a choice to the
+ *   person, a card with the options and Send (each recorded first, so its buttons mean something). A card holds the words only
+ *   when they are short and not shown already.
  * - Then a card for each file the item's worker delivered, with Claw's own download link.
  *
  * Every word of this worker's own is in the person's language, never in that of what was said.
@@ -51,10 +52,17 @@ export declare class SayPlanner {
     /** The replies to tap, under the last of what was said, when no card follows. */
     private withReplies;
     /**
-     * The card with buttons the event asks for, recorded first: a result that waits, a write Claw holds, or a command put to the
-     * person; undefined for none. `holdsWords`: the card shows the words, which are then not said apart.
+     * The card with buttons the event asks for, recorded first: a result that waits, a write Claw holds, a command or a choice put
+     * to the person; undefined for none. `holdsWords`: the card shows the words, which are then not said apart.
      */
     private card;
+    /** A write Claw holds for the person (Allow, Deny) or a command put to them (Run, Cancel), recorded first; undefined for none. */
+    private askCard;
+    /**
+     * A choice put to the person (`choices`): its options and Send, recorded first (what a press sends is read from the record).
+     * Its Send sends what was picked as the person's own message.
+     */
+    private choiceCard;
     /** What was said, as AI answers with thumbs, each with the citations its own words cite (when the whole text cites at all). */
     private said;
     /** A result that waits: Accept and Stop, and (a task whose result names a pull request) auto-reply on or off. */

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

@@ -68,9 +68,31 @@ export interface ConfirmWriteModel {
     readonly allowLabel: string;
     readonly lang: string;
 }
+/** A choice the assistant put to the person: its options as radio buttons (or check boxes) and Send. */
+export interface ChoiceCardModel {
+    /** The words, when the card holds them ("" when they were said apart). */
+    readonly text: string;
+    readonly cardId: string;
+    readonly options: readonly string[];
+    /** Several may be picked (check boxes); else one (radio buttons). */
+    readonly multiple: boolean;
+    /** One line under the options when the card comes back unanswered ("" none). */
+    readonly note: string;
+    /** "zh" or "en"; null to follow what was said. */
+    readonly lang: string | null;
+}
+/** What replaces a choice card once the person sent what they picked: what they sent, under the words it answered. */
+export interface ChoiceChosenModel {
+    readonly text: string;
+    /** The options picked, in the card's order. */
+    readonly chosen: readonly string[];
+    readonly lang: string | null;
+}
 declare module "../ports/surface.js" {
     interface ViewMap {
         actionCard: ActionCardModel;
+        choiceCard: ChoiceCardModel;
+        choiceChosen: ChoiceChosenModel;
         board: BoardModel;
         confirmWrite: ConfirmWriteModel;
         workCard: WorkCardModel;

package/dist/types/language/chosen.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The language a person chose to be answered in (`/lang zh|en`), as it goes to Claw with each of their messages, so that the
+ * model's answer is in it as well as the agent's own texts.
+ *
+ * Only a choice the person said counts: a language learnt from what they write (`learnLang`), and `/lang auto`, are no
+ * choice, nothing is sent, and Claw reads the language from the message as before. To the assistant the choice goes in the
+ * message's `channel_context` (`reply_language`); to a plain session (a 1:1 chat without the assistant) as the line Claw's
+ * assistant uses for it, after the message (`replyLanguageLine`). A group's turn carries the group's language in that line
+ * instead (`groupChosenLang`): in a group a person's own choice is not read.
+ */
+import type { Lang } from "../locales/lang.js";
+/** What of a person's preferences says the choice (`Prefs.lang`, `Prefs.langSet`). */
+export interface LangPrefs {
+    readonly lang: string;
+    readonly langSet: boolean;
+}
+/** The language the person chose, or undefined when they chose none. */
+export declare function chosenLang(prefs: LangPrefs): Lang | undefined;
+/** The choice as `channel_context` carries it (`{ reply_language: "zh" }`); empty when there is none. */
+export declare function replyLanguageContext(prefs: LangPrefs): {
+    reply_language?: Lang;
+};
+/** The line after a message to a plain session that names the language to answer in: `[Reply language: English]`. */
+export declare function replyLanguageLine(lang: Lang): string;

package/dist/types/language/group.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What a group chat says to set the language it is answered in: `/lang zh|en|auto` (`/lang` alone asks which it is), or one of a
+ * few sentences that name the group ("这个群用英文", "本群跟随提问者的语言", "use English in this group", "set the group language to
+ * Chinese"). Only the whole message counts. A sentence that does not name the group ("用英文回复", "answer in English") is no
+ * setting: it asks for that one answer in that language, and goes to the agent as it is.
+ */
+import type { GroupLanguage } from "../ports/store/group-language.js";
+/** A group's language command: set it, say which it is, or how to write it. */
+export type GroupLangCommand = {
+    readonly kind: "set";
+    readonly lang: GroupLanguage;
+} | {
+    readonly kind: "status";
+} | {
+    readonly kind: "usage";
+};
+/** The group's language command `text` is (`/lang …` or a sentence that sets it), or undefined when it is none. */
+export declare function parseGroupLang(text: string): GroupLangCommand | undefined;

package/dist/types/locales/assistant-cards.d.ts

@@ -67,6 +67,21 @@ export declare const assistantCardText: import("./catalog.js").Catalog<{
     askedTitle: (p: {
         n: number;
     }) => string;
+    choiceTitle: string;
+    choiceTitleMany: string;
+    choiceSend: string;
+    choiceTyped: string;
+    choiceNone: string;
+    choiceSent: (p: {
+        answer: string;
+    }) => string;
+    choiceGone: string;
+    choiceSending: (p: {
+        answer: string;
+    }) => string;
+    choiceFailed: string;
+    /** How the options picked are joined into the person's message. */
+    choiceJoin: string;
     version: (p: {
         version: number;
     }) => string;

package/dist/types/locales/group-language.d.ts

@@ -0,0 +1,32 @@
+import type { GroupLanguage } from "../ports/store/group-language.js";
+/** The announcement, in the chat, of a change of its language by `name` ("" when the channel gave none). */
+export declare function groupLanguageSet(lang: GroupLanguage, name: string): string;
+/** The card the first @mention in a chat with no language puts to its members. */
+export declare const GROUP_LANGUAGE_CARD: {
+    title: string;
+    text: (p: {
+        bot: string;
+    }) => string;
+    buttons: {
+        zh: string;
+        en: string;
+        auto: string;
+    };
+};
+export declare const groupLanguageText: import("./catalog.js").Catalog<{
+    isZh: (p: {
+        bot: string;
+    }) => string;
+    isEn: (p: {
+        bot: string;
+    }) => string;
+    isAuto: (p: {
+        bot: string;
+    }) => string;
+    isNone: (p: {
+        bot: string;
+    }) => string;
+    usage: (p: {
+        bot: string;
+    }) => string;
+}>;

package/dist/types/locales/group.d.ts

@@ -1,4 +1,4 @@
-/** What a group chat is told. Most of it is English only, as in the Python worker. */
+/** What a group chat is told, in the group's language (`Chat.lang`). */
 export declare const groupText: import("./catalog.js").Catalog<{
     githubOneToOne: string;
     oneToOneOnly: (p: {

package/dist/types/locales/terminal-approvals.d.ts

@@ -20,7 +20,11 @@ export declare const terminalApprovalText: import("./catalog.js").Catalog<{
         name: string;
     }) => string;
     firstAnswerWins: string;
+    afterCard: string;
+    onInput: string;
     tooLong: string;
+    tooLongAfterCard: string;
+    tooLongOnInput: string;
     questionOf: (p: {
         n: number;
         of: number;
@@ -31,6 +35,7 @@ export declare const terminalApprovalText: import("./catalog.js").Catalog<{
     optionNoStop: string;
     optionPlanApprove: string;
     optionPlanKeep: string;
+    optionToTerminal: string;
     answeredInTerminal: string;
     noLongerWaiting: string;
     answeredInTerminalLine: string;

package/dist/types/ports/store/assistant.d.ts

@@ -1,6 +1,6 @@
 /**
  * Cards and messages of the assistant (tables `assistant_cards`, `auto_replies`, `assistant_action_cards`,
- * `assistant_confirm_cards`, `assistant_messages`). A card's buttons carry only its id; what a press means is read
+ * `assistant_confirm_cards`, `assistant_choice_cards`, `assistant_messages`). A card's buttons carry only its id; what a press means is read
  * from here, so a forged, old or someone else's card changes nothing.
  */
 import type { JsonObject } from "./json.js";
@@ -56,6 +56,21 @@ export interface ConfirmCard {
     readonly state: CardState;
     readonly createdAt: number;
 }
+/** A choice the assistant put to the person: what was asked, the options, and (once sent) what was picked. */
+export interface ChoiceCard {
+    readonly cardId: string;
+    readonly userId: string;
+    /** The words the card holds ("" when they were said apart). */
+    readonly text: string;
+    readonly options: readonly string[];
+    readonly multiple: boolean;
+    /** What was picked, in the card's order: being sent ('busy') or sent ('done'); empty before the first press. */
+    readonly chosen: readonly string[];
+    /** 'open'; 'busy' while a press sends it; 'done' once the router took it. */
+    readonly state: CardState;
+    readonly lang: string;
+    readonly createdAt: number;
+}
 export interface AssistantMessage {
     readonly userId: string;
     /** The actions (and handoffs) the message declared. */
@@ -94,6 +109,17 @@ export interface AssistantButtonRepository {
     /** Null once it is older than CONFIRM_CARD_KEEP_SECONDS. */
     getConfirmCard(cardId: string): ConfirmCard | null;
     moveConfirmCard(cardId: string, state: CardState, options?: MoveOptions): boolean;
+    addChoiceCard(userId: string, choice: {
+        readonly text: string;
+        readonly options: readonly string[];
+        readonly multiple: boolean;
+        readonly lang: string;
+    }): string;
+    /** Null once it is older than ASSISTANT_MESSAGE_KEEP_SECONDS. */
+    getChoiceCard(cardId: string): ChoiceCard | null;
+    /** An open card is claimed by a press to send `chosen` (it moves to 'busy'); true if this call claimed it, so of two presses exactly one sends. */
+    claimChoiceCard(cardId: string, chosen: readonly string[]): boolean;
+    moveChoiceCard(cardId: string, state: CardState, options?: MoveOptions): boolean;
 }
 export interface AssistantMessageRepository {
     /** A message this worker sent to the person's assistant, with the actions it declared and the Claw users it named. */

package/dist/types/ports/store/group-language.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The language each group chat is answered in, as its members set it (`@bot /lang en|zh|auto`, "这个群用英文", or a pick on the
+ * card the bot posts the first time it is @mentioned there). `auto`: each question is answered in the language it is asked in.
+ * A chat the card was put to and nobody answered yet is kept as asked (`lang` ""), so it is never asked again. Who set it is
+ * never stored: the announcement names them once, in the chat.
+ */
+export type GroupLanguage = "zh" | "en" | "auto";
+export interface GroupLanguageRepository {
+    /** The chat's language; "" when it was asked and nobody chose; null when it was never asked nor set. */
+    groupLanguage(conversationId: string): GroupLanguage | "" | null;
+    /** Sets it (anyone in the chat may). */
+    setGroupLanguage(conversationId: string, lang: GroupLanguage): void;
+    /**
+     * Records that the chat is asked now: true when this call recorded it (it was never asked nor set), false when it was already, in
+     * one step, so that two @mentions at once put one card.
+     */
+    markGroupLanguageAsked(conversationId: string): boolean;
+    /** The question could not be put after all: the chat is asked again next time (nothing is undone once somebody chose). */
+    unmarkGroupLanguageAsked(conversationId: string): void;
+}

package/dist/types/ports/store/index.d.ts

@@ -14,6 +14,7 @@ import type { AssistantButtonRepository, AssistantCardRepository, AssistantMessa
 import type { FeedbackRepository } from "./feedback.js";
 import type { GithubConfirmationRepository, ReviewDelegationRepository } from "./github.js";
 import type { GroupContextRepository } from "./group-context.js";
+import type { GroupLanguageRepository } from "./group-language.js";
 import type { IdempotencyRepository } from "./idempotency.js";
 import type { LinkRepository } from "./link.js";
 import type { NotifySubscriptionRepository } from "./notify.js";
@@ -33,6 +34,7 @@ export interface StorePort {
     readonly approvals: ApprovalRepository;
     readonly observe: ObserveRepository;
     readonly groupContext: GroupContextRepository;
+    readonly groupLanguage: GroupLanguageRepository;
     readonly assistantCards: AssistantCardRepository;
     readonly assistantButtons: AssistantButtonRepository;
     readonly assistantMessages: AssistantMessageRepository;
@@ -55,6 +57,7 @@ export type * from "./assistant.js";
 export type * from "./feedback.js";
 export type * from "./github.js";
 export type * from "./group-context.js";
+export type * from "./group-language.js";
 export type * from "./idempotency.js";
 export type * from "./link.js";
 export type * from "./notify.js";

package/dist/types/ports/surface.d.ts

@@ -134,6 +134,12 @@ export interface InboundMessage extends InboundBase {
      */
     readonly unreadableFiles: readonly string[];
     readonly provenance: Provenance;
+    /**
+     * What was picked on a choice card the assistant put (`assistant_choice`): an answer, never read as a command. The menu's
+     * words and help's phrases ("New", "重新开始", "Stop", "关闭记忆") stay the words picked; it goes where a typed message that
+     * is no command goes (the assistant, or the agent a 1:1 chat is attached to).
+     */
+    readonly choice?: true;
 }
 /** A button pressed on a card the bot posted. */
 export interface InboundAction extends InboundBase {

package/dist/types/protocol/claw-api/assistant-events.d.ts

@@ -121,8 +121,8 @@ export interface AssistantRemoteAsk {
     /** When the connector stops waiting for an answer (it refuses the request then); absent when it did not say. */
     expires_at?: string;
     /**
-     * `terminal`: asked in a terminal on the machine (a conversation its person started there), whose own prompt stays open: whichever
-     * answer comes first is taken. Absent for a session opened through Claw.
+     * `terminal`: asked in a terminal on the machine (a conversation its person started there), which asks it too (when: see
+     * `terminal_asks`); whichever answer comes first is taken. Absent for a session opened through Claw.
      */
     origin?: "terminal";
     /** A terminal's request: what kind of prompt it is (`execute`, `edit`, `question`, `switch_mode` for a plan, `mcp`, `other`). */
@@ -139,6 +139,22 @@ export interface AssistantRemoteAsk {
     /** A terminal's question asked as several cards: which this is (from 0), and how many. */
     question_index?: number;
     question_count?: number;
+    /**
+     * A terminal's request: when the terminal asks it too, as its connector said (`terminal_asks` on the request). Absent: alongside
+     * the card, and the first answer counts (Claude Code). `after_card`: only once the card is answered or its time is up, and the
+     * card offers only to decline or to hand it back to the terminal (Cursor). `on_input`: only once someone types in that terminal,
+     * which withdraws the card (Codex).
+     */
+    terminal_asks?: TerminalAsks;
+}
+/** When a terminal asks a request that is also on a card, besides alongside it: see {@link AssistantRemoteAsk.terminal_asks}. */
+export type TerminalAsks = "after_card" | "on_input";
+/** The values of `terminal_asks` a channel knows; any other is read as absent. */
+export declare const TERMINAL_ASKS: readonly TerminalAsks[];
+/** A choice a say puts to the person: from 2 to 10 options, one plain line each; `multiple` when several may be picked. */
+export interface AssistantSayChoice {
+    options: string[];
+    multiple: boolean;
 }
 /** Something the assistant chose to say to the user. */
 export interface AssistantSayPayload extends AssistantEventBase {
@@ -151,6 +167,12 @@ export interface AssistantSayPayload extends AssistantEventBase {
      * next, each one plain line. A channel shows them as buttons that send the words as the user's message; one that cannot ignores them.
      */
     suggested_replies?: string[];
+    /**
+     * Present only when the router put a choice to the person (`CLAW_ASSISTANT_CHOICES`): the options they pick from, each one plain
+     * line, and whether they may pick several. A channel shows them as a card whose Send sends the picked options as the person's own
+     * message (their words, joined); one that cannot ignores it, and the text still names the options.
+     */
+    choices?: AssistantSayChoice;
     confirm_write?: AssistantConfirmWrite;
     /** Files the user gets with the message (a worker's deliveries, `deliveries.ts`): one download each. */
     files?: AssistantFile[];

package/dist/types/remote-view/terminal-ask-view.d.ts

@@ -1,7 +1,9 @@
 /**
  * The card of a question a terminal asks: a coding agent its person started in their own terminal wants to run a command, change
  * a file, start on a plan or have a multiple-choice question answered, and the connector's approval hooks put it here too
- * (`remote.ask` with `origin: "terminal"`). The terminal keeps asking: the first answer counts.
+ * (`remote.ask` with `origin: "terminal"`). The terminal asks too, as the request's `terminal_asks` says (`terminalAsksOf`): alongside
+ * the card, the first answer counting (Claude Code); only once the card is answered or its wait is over (Cursor); or once someone
+ * types in that terminal, which takes the question back from the card (Codex). The card says which.
  *
  * Nothing is approved unseen. The card shows the request whole (the connector and Claw carry it whole, credentials masked); a
  * request whose content did not come (Claw leaves it out past its size), or that is longer than a card shows, keeps only the
@@ -9,6 +11,7 @@
  * masked in it (a mask can hide more than the credential), or a character the card does not show as itself.
  */
 import type { Lang } from "../locales/lang.js";
+import { type TerminalAsks } from "../protocol.js";
 import type { DecisionButton } from "../remote/actions.js";
 import { type PermissionOption } from "../remote/options.js";
 import type { Reported } from "../remote/reported.js";
@@ -62,6 +65,13 @@ export interface TerminalAsk {
     readonly machine: string;
     readonly agent: string;
 }
+/**
+ * When the terminal asks a request that is also on a card (`remote.ask`'s `terminal_asks`, from the connector through Claw):
+ * `after_card`, only once the card is answered or its wait is over, and the card offers only to decline or hand it back (Cursor);
+ * `on_input`, only once someone types in that terminal, which withdraws the card (Codex); undefined (absent, or a value this
+ * client does not know), alongside the card, the first answer counting (Claude Code).
+ */
+export declare function terminalAsksOf(ask: Reported): TerminalAsks | undefined;
 /** Whether `remote.ask` is a question a terminal asks (a connector's approval hooks), not one an agent Claw started asks. */
 export declare function isTerminalAsk(ask: Reported | undefined): boolean;
 /** The card of a question a terminal asks. */

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

@@ -19,6 +19,15 @@ export declare function learnLang(store: Pick<RouterStore, "prefs">, userId: str
  * "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;
+/**
+ * The language a group chat is answered in, its fixed texts and its answers alike: the one its members set (`/lang zh|en` there,
+ * or a pick on its language card); else (none set, or "follow the asker") the language of the message being answered (`written`).
+ * A person's own choice (`/lang` in their 1:1 chat) is not read here: in a group the group decides. A message that says no
+ * language of its own ("/new", a link) is answered in the one the sender's messages were last written in, else their client's.
+ */
+export declare function groupLangOf(store: Pick<RouterStore, "prefs"> & Partial<Pick<RouterStore, "groupLanguage">>, conversationId: string, userId: string, locale: string, written: string): Lang;
+/** The language a group chat's members set, when it is one (`/lang zh|en`); undefined for none, and for "follow the asker". */
+export declare function groupChosenLang(store: Partial<Pick<RouterStore, "groupLanguage">>, conversationId: string): Lang | undefined;
 /** One chat as the router answers in it: who wrote, where to answer, and in which language. */
 export declare class Chat {
     private readonly store;
@@ -28,11 +37,16 @@ export declare class Chat {
     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, 
+    /** The words of the message being answered ("" for a click, and for work that runs on its own): a group's language without one. */
+    readonly written: string;
+    constructor(store: Pick<RouterStore, "prefs"> & Partial<Pick<RouterStore, "groupLanguage">>, 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);
+    locale: string, 
+    /** The words of the message being answered ("" for a click, and for work that runs on its own): a group's language without one. */
+    written?: string);
+    /** In a 1:1 chat the person's language (`langOf`); in a group, the group's (`groupLangOf`). */
     lang(): Lang;
     zh(): boolean;
     say(text: string): Promise<void>;

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

@@ -38,7 +38,7 @@ export interface RouterConfig {
     readonly ownThumbsMobile: boolean;
 }
 /** The repositories the router reads and writes (the W1 store, as far as routing goes). */
-export type RouterStore = Pick<StorePort, "links" | "references" | "prefs" | "members" | "sessions" | "repoHistory" | "turns" | "onboarding" | "idempotency" | "assistantMessages" | "notifySubs" | "reviewDelegation" | "approvals" | "now">;
+export type RouterStore = Pick<StorePort, "links" | "references" | "prefs" | "groupLanguage" | "members" | "sessions" | "repoHistory" | "turns" | "onboarding" | "idempotency" | "assistantMessages" | "notifySubs" | "reviewDelegation" | "approvals" | "now">;
 /** The per-person limits (Python `limits.py`): messages per window and tasks at the same time. */
 export interface RouterLimits {
     readonly maxConcurrentTasks: number;

package/dist/types/routing/group-language.d.ts

@@ -0,0 +1,25 @@
+import type { InboundAction } from "../ports/surface.js";
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+/** The verb of the language card's buttons. */
+export declare const GROUP_LANG_VERB = "group_lang";
+/**
+ * The language a group chat is answered in, as its members set it (the store's `groupLanguage`): `@bot /lang zh|en|auto` or a
+ * sentence that names the group ("这个群用英文"), and a card the first time the bot is @mentioned in a chat that has none. Anyone in
+ * the chat may set it, with no Claw credential (it is the chat's, not one person's), and every change is announced in the chat with
+ * the name of who made it. The group's language then governs everything said there (`Chat.lang`, `groupLangOf`) and the language
+ * its turns are asked to answer in (`TurnStarter`).
+ */
+export declare class GroupLanguages {
+    private readonly ctx;
+    constructor(ctx: RouterContext);
+    /** `/lang …` or a sentence that sets the group's language: answered here; false when `text` is neither. */
+    command(chat: Chat, text: string): Promise<boolean>;
+    /**
+     * The first @mention in a chat that has no language: the card that asks its members which, once (the chat is recorded as asked
+     * before the card goes, so two mentions at once put one; a card that could not be posted is asked again next time).
+     */
+    askOnce(chat: Chat): Promise<void>;
+    /** A pick on the language card, by anyone in the chat: the language is set, the card says so, and so does the chat. */
+    click(action: InboundAction, chat: Chat): Promise<void>;
+}

package/dist/types/routing/group-router.d.ts

@@ -3,6 +3,7 @@ import type { InboundAction, InboundMessage } from "../ports/surface.js";
 import { type Chat } from "./chat.js";
 import type { SessionCommands } from "./commands-session.js";
 import type { RouterContext } from "./context.js";
+import { type GroupLanguages } from "./group-language.js";
 import type { GroupRemote } from "./group-remote.js";
 import type { Onboarding } from "./onboarding.js";
 import { type PersonalText } from "./personal-text.js";
@@ -18,7 +19,8 @@ export declare class GroupRouter {
     private readonly onboarding;
     private readonly remote;
     private readonly starter;
-    constructor(ctx: RouterContext, text: PersonalText, sessions: SessionCommands, onboarding: Onboarding, remote: GroupRemote, starter: TurnStarter);
+    private readonly languages;
+    constructor(ctx: RouterContext, text: PersonalText, sessions: SessionCommands, onboarding: Onboarding, remote: GroupRemote, starter: TurnStarter, languages: GroupLanguages);
     route(event: InboundMessage | InboundAction, chat: Chat): Promise<void>;
     /** A button in a group: only those of the presser's own cards that may be pressed there answer. */
     private click;

package/dist/types/routing/personal-text.d.ts

@@ -15,7 +15,8 @@ export declare class PersonalText {
     constructor(ctx: RouterContext, commands: CommandTable, starter: TurnStarter);
     /**
      * What the person wrote, with a word of the commands menu read as its command and a sentence help teaches read as the
-     * command it means; a sentence for what this chat cannot do right now stays words.
+     * command it means; a sentence for what this chat cannot do right now stays words. A choice picked on the assistant's card
+     * is the words picked, never a command.
      */
     textOf(message: InboundMessage, group?: boolean): string;
     onText(message: InboundMessage, chat: Chat, key: string): Promise<void>;

package/dist/types/routing/turn-runner.d.ts

@@ -43,6 +43,12 @@ export interface TurnRun {
     readonly sent: string;
     readonly files: readonly InboundFile[];
     readonly lang: Lang;
+    /**
+     * The language the turn is to be answered in, told to Claw after the message: in a 1:1 chat the one the person chose (`/lang
+     * zh|en`, `chosenLang`), in a group the group's (`groupChosenLang`); undefined: none was chosen, and the answer is in the language
+     * of what they wrote. A chat turn's only: a review's follows its request.
+     */
+    readonly replyLang?: Lang;
     /** The answer gets thumbs of the worker's own (a phone, whose own thumbs never reach the worker). */
     readonly ownThumbs: boolean;
     /** Claw pushes this person a run's end and its approvals. */

package/dist/types/routing/turn-start.d.ts

@@ -1,7 +1,7 @@
 import type { Lang } from "../locales/lang.js";
 import type { Logger } from "../ports/logger.js";
 import type { InboundFile } from "../ports/surface.js";
-import type { Chat } from "./chat.js";
+import { type Chat } from "./chat.js";
 import type { RouterContext } from "./context.js";
 import type { ReviewRunFields, TurnOutcome } from "./turn-runner.js";
 /** Teams on a phone or a tablet: its own Stop under a reply is greyed out, and its own thumbs never reach the worker. */
@@ -72,7 +72,7 @@ export declare class TurnStarter {
     /** The turns that run now (a test waits for them). */
     settled(): Promise<void>;
     /** The turn that runs (its end is `done`), or undefined when none was started (the person was told why). */
-    start(request: StartTurn): Promise<RunningTurn | undefined>;
+    start(started: StartTurn): Promise<RunningTurn | undefined>;
     /** A typed message the waiting question card of the chat's session took as its answer (`question-reply.ts`). */
     private answersQuestion;
     private track;
@@ -97,6 +97,11 @@ export declare class TurnStarter {
     /** What the run reads of the chat's session: its id, the model it has, the repository a new one is bound to. */
     private sessionPart;
     private runOf;
+    /**
+     * The language a chat turn is to be answered in, when one was chosen (a review's answer follows its request's language): in a
+     * group the group's (`groupChosenLang`; the sender's own choice is not read there), in a 1:1 chat the person's.
+     */
+    private replyLang;
     private hooks;
     private guarded;
     private tell;

package/dist/types/turn/engine/context.d.ts

@@ -1,4 +1,3 @@
-/** Everything one turn runs with: who it acts for, what it sends, where it answers, and what it reports back. */
 import type { Lang } from "../../locales/lang.js";
 import type { PullRef } from "../../claw/model.js";
 import type { Integrations } from "../../plugins/integrations.js";
@@ -60,6 +59,8 @@ export interface TurnRequest {
     readonly sent?: string;
     /** The language the person is answered in (undefined: the language of `text`). */
     readonly lang?: Lang;
+    /** The language the person chose to be answered in, told to Claw after the message (`replyLanguageLine`); undefined: none chosen. */
+    readonly replyLang?: Lang;
     /** What the user sent with the message. */
     readonly files?: readonly InboundFile[];
 }
@@ -154,6 +155,7 @@ export declare function credential(ctx: TurnContext): Promise<string>;
 export declare function langOf(ctx: TurnContext): Lang;
 /**
  * What Claw is sent: the quoted messages, then what the user wrote (with the addresses behind its links), then where the
- * files they sent are. `text` stays the words alone: the session's title, the language of the answer.
+ * files they sent are, then the language they chose to be answered in (`replyLanguageLine`), when they chose one. `text` stays the
+ * words alone: the session's title, the language of the answer.
  */
 export declare function messageOf(ctx: TurnContext): string;