@primusclaw/personal-agent 0.4.0 → 0.6.0

package/dist/types/approvals/questions.d.ts

@@ -34,3 +34,10 @@ export interface Answers {
  * typed; a choice the card never offered is ignored.
  */
 export declare function answersOf(data: Readonly<Record<string, unknown>>): Answers;
+/**
+ * A message the person typed in the chat while a question card waited, taken as the card's answer. With one question, a
+ * reply that names its options (by label or by number, several of them for a multiple choice) answers with their labels,
+ * as a press on the card would; any other reply is the free answer the card's text box takes. With several questions the
+ * whole reply answers each of them: the agent reads which part answers which. Nothing is skipped.
+ */
+export declare function typedAnswers(questions: readonly CardQuestion[], typed: string): Answers;

package/dist/types/approvals/records.d.ts

@@ -35,8 +35,8 @@ export declare const TURN_DEADLINE_SECONDS: number;
  * the person the turn is for (Python `store.save_approval(sender.aad_id, ...)`).
  */
 export interface TurnApprovalRecords {
-    record(userId: string, sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope): boolean;
-    sent(sessionId: string, toolUseId: string): void;
+    record(userId: string, sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope, questions?: unknown): boolean;
+    sent(sessionId: string, toolUseId: string, cardId?: string): void;
     unsent(sessionId: string, toolUseId: string): void;
 }
 /** The records of the approvals a turn shows (the Python `on_approval`, `on_approval_sent`, `on_approval_unsent`). */

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

@@ -3,6 +3,7 @@
  * channel adapter renders them; `approvalView` (approval-view.ts) is what an approval card says.
  */
 import type { JsonObject } from "../json.js";
+import type { Lang } from "../locales/lang.js";
 import type { CardQuestion } from "./questions.js";
 /** An approval card: the arguments of the Python worker's `render.permission_card`, one for one. */
 export interface ApprovalCardModel {
@@ -27,6 +28,11 @@ export interface QuestionCardModel {
     readonly ownerName: string;
     /** A line under the header: which task asks, or what happened when the card comes back after a click ("" when none). */
     readonly note: string;
+    /**
+     * The card says it can also be answered by a message in the chat: a turn's question, which a typed message answers
+     * (`routing/question-reply.ts`). A work item's question is answered on its card only.
+     */
+    readonly typedReply?: boolean;
 }
 /** What replaces an approval card once it was answered (render.decided_card). */
 export interface ApprovalDecidedModel {
@@ -47,6 +53,8 @@ export interface QuestionAnsweredModel {
     readonly answers: readonly (readonly [string, string])[];
     readonly when: number;
     readonly zone: string;
+    /** Answered by a message typed in the chat (not on the card), in this language: the card says "Answered: <answer>". */
+    readonly replied?: Lang;
 }
 /** An approval card put back after a press that did not go through: the note, then Approve and Deny again. */
 export interface ApprovalAgainModel {

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/receipts.d.ts

@@ -62,7 +62,7 @@ export declare class ReceiptConversation implements Conversation {
     update(id: MessageId, message: OutMessage, options?: UpdateOptions): Promise<void>;
     delete(id: MessageId): ReturnType<Conversation["delete"]>;
     outgoing(message: OutMessage): Envelope;
-    deliver(envelope: Envelope): Promise<void>;
+    deliver(envelope: Envelope): Promise<MessageId | undefined>;
     openStream(replyTo: MessageId, status: string): ReturnType<Conversation["openStream"]>;
     /** What the assistant said beside the handoff, when no text message carried it: said on its own. */
     sayPostscript(): Promise<void>;

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,23 @@
+/**
+ * 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 group's turn, or a 1:1 chat without the assistant) as
+ * the line Claw's assistant uses for it, after the message (`replyLanguageLine`).
+ */
+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/locales/approval.d.ts

@@ -28,4 +28,15 @@ export declare const approvalText: import("./catalog.js").Catalog<{
     }) => string;
     questionAsker: string;
     send: string;
+    /** Under a question card's questions: a client that does not show the card can still answer. */
+    questionReply: string;
+    /** The same in a group chat, where only a message that @mentions the bot reaches it. */
+    questionReplyGroup: string;
+    /** A question card once a message typed in the chat answered it. */
+    questionReplied: (p: {
+        answer: string;
+    }) => string;
+    questionRepliedAt: (p: {
+        at: string;
+    }) => string;
 }>;

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/turn.d.ts

@@ -21,6 +21,8 @@ export declare const turnText: import("./catalog.js").Catalog<{
     thinking: string;
     /** A turn still running when its stream has to close: the answer follows as a message of its own. */
     stillWorking: string;
+    /** A turn whose stream is closed because a card now waits for the person's choice. */
+    awaitingChoice: string;
     interrupted: string;
     /** What a turn the person stopped ends with. */
     stopped: string;

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

@@ -25,12 +25,29 @@ export interface NewApproval {
     readonly expiresAt: number;
     /** The card as it will be published, kept until `approvalSent` so a worker that dies before the send leaves it to the next. */
     readonly envelope?: JsonObject | null;
+    /**
+     * A question card of a turn: its questions as the card's button carries them. Kept so that what the person types next in
+     * the chat can be taken as the answer (`pendingQuestion`).
+     */
+    readonly questions?: readonly JsonObject[] | null;
+}
+/** A question card still waiting for its answer, with what it takes to answer it from a typed message. */
+export interface PendingQuestion {
+    readonly sessionId: string;
+    readonly toolUseId: string;
+    readonly userId: string;
+    /** When it runs out, epoch seconds. */
+    readonly expiresAt: number;
+    /** The questions as recorded with the card (`NewApproval.questions`). */
+    readonly questions: readonly JsonObject[];
+    /** The chat's id of the card ("" when the channel never said it: the card cannot be edited). */
+    readonly cardId: string;
 }
 export interface ApprovalRepository {
     /** True when this call recorded it; false when a card for the same approval was recorded before. */
     saveApproval(approval: NewApproval): boolean;
-    /** The card reached the chat: nothing is left to send. */
-    approvalSent(sessionId: string, toolUseId: string): void;
+    /** The card reached the chat: nothing is left to send. `cardId`: the chat's id of the card, when it said it. */
+    approvalSent(sessionId: string, toolUseId: string, cardId?: string): void;
     /** Its card is being sent right now by this process and may still fail. */
     approvalInFlight(sessionId: string, toolUseId: string): boolean;
     /** The card never reached the chat: take the record back (a row answered meanwhile stays). */
@@ -40,6 +57,11 @@ export interface ApprovalRepository {
     /** A claimed card could not be sent: the next sweep tries again. */
     approvalSendFailed(sessionId: string, toolUseId: string): void;
     getApproval(sessionId: string, toolUseId: string): Approval | null;
+    /**
+     * The newest question card of `userId` in `sessionId` that is still pending, in time, and was recorded with its questions;
+     * null when there is none.
+     */
+    pendingQuestion(sessionId: string, userId: string): PendingQuestion | null;
     /** Move an approval to `state`; true if this call did it (only from 'pending' unless `onlyIfPending` is false). */
     closeApproval(sessionId: string, toolUseId: string, state: ApprovalState, options?: {
         readonly onlyIfPending?: boolean;

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/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 {
@@ -336,8 +342,11 @@ export interface Conversation {
     delete(id: MessageId): Promise<Result<void, DeleteUnsupported>>;
     /** The envelope `send` would publish for `message` (masked in a group), built without sending it. */
     outgoing(message: OutMessage): Envelope;
-    /** Publish an envelope `outgoing` built (possibly in another process, from storage). */
-    deliver(envelope: Envelope): Promise<void>;
+    /**
+     * Publish an envelope `outgoing` built (possibly in another process, from storage). The id of the posted message when the
+     * channel said it at once (a direct send); undefined otherwise (a queued send: the message cannot be edited by id).
+     */
+    deliver(envelope: Envelope): Promise<MessageId | undefined>;
     /**
      * A live stream that answers `replyTo` (the person's message), showing `status` as its first informative update.
      * Success means that first update has been sent and the channel took it; refused when the channel cannot stream here

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

@@ -140,6 +140,11 @@ export interface AssistantRemoteAsk {
     question_index?: number;
     question_count?: number;
 }
+/** 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 {
     type: "assistant.say";
@@ -151,6 +156,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/routing/credentials.d.ts

@@ -1,4 +1,6 @@
-import type { OutMessage } from "../ports/surface.js";
+import type { LinkRepository } from "../ports/store/link.js";
+import type { OutMessage, UserRef } from "../ports/surface.js";
+import type { TokenExchange } from "../plugins/token-exchange.js";
 import type { Chat } from "./chat.js";
 import type { RouterDeps } from "./deps.js";
 import type { CredentialProvider } from "./features.js";
@@ -12,6 +14,12 @@ export declare const IDENTITY_CARD_INTERVAL_SECONDS: number;
 /** Its kind in the store's notice record (`claimGithubNotice`): the time it was last sent to the person. */
 export declare const IDENTITY_CARD_NOTICE = "identity_card";
 type CredentialDeps = Pick<RouterDeps, "store" | "exchange" | "config" | "logger">;
+/**
+ * What an action of the person's outside a turn (a thumb on an answer) calls Claw with: what their chats run on, so it acts
+ * on the same session as the same Claw user. With chats on the exchange (`exchange` given), the person's exchanged token,
+ * else their linked key; without, the linked key. Undefined when they have neither. Never asks or tells them anything.
+ */
+export declare function chatCredentialOf(links: Pick<LinkRepository, "getKey">, exchange: TokenExchange | undefined): (sender: UserRef) => Promise<string | undefined>;
 /**
  * What Claw is called with for a person, and what a person who has none is told (the Python `Agent._credential`,
  * `_unlinked`, `_connect_identity`, `_binding_card`, `_ask_to_link`, `_background_credential`, `_fresh_credential`).

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" | "now">;
+export type RouterStore = Pick<StorePort, "links" | "references" | "prefs" | "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/personal-text.d.ts

@@ -2,7 +2,7 @@ import type { InboundFile, InboundMessage } from "../ports/surface.js";
 import type { Chat } from "./chat.js";
 import type { CommandTable } from "./command-table.js";
 import type { RouterContext } from "./context.js";
-import type { TurnStarter } from "./turn-start.js";
+import { type TurnStarter } from "./turn-start.js";
 /**
  * A 1:1 message that is not one of the chat's commands, as it goes on (the Python `Agent._text_of`, `_on_text`,
  * `_sent_on`, `_talks_to_agent`, `_session_control`, `_understand`, `_understood`, `_offer_github`, `_attachments`):
@@ -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/question-reply.d.ts

@@ -0,0 +1,22 @@
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+/**
+ * A question with less than this left of its wait is not answered from a typed message: Brain may already have stopped
+ * waiting (the card's time is counted from when the worker saw the question, a little after Brain's), and an answer nobody
+ * waits for is dropped. The message then goes on as a new one, as before.
+ */
+export declare const TYPED_ANSWER_MARGIN_SECONDS = 15;
+/** A typed message that may answer the person's waiting question. */
+export interface TypedReply {
+    readonly chat: Chat;
+    readonly text: string;
+    /** The Claw credential of the person, read when there is a question to answer. */
+    readonly credential: () => Promise<string>;
+}
+/**
+ * Answers the question card that waits in the chat's session with `reply.text`: true when it did (the card now says
+ * "Answered: ...", and the message must not go on as a new one); false when there was nothing to answer, or it could not be
+ * answered (the message then goes on as before). Only the person the card was raised for answers it: their own session in
+ * this chat, their own record.
+ */
+export declare function answerWaitingQuestion(ctx: RouterContext, reply: TypedReply): Promise<boolean>;

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

@@ -43,6 +43,11 @@ export interface TurnRun {
     readonly sent: string;
     readonly files: readonly InboundFile[];
     readonly lang: Lang;
+    /**
+     * The language the person chose to be answered in (`/lang zh|en`, `chosenLang`), told to Claw after the message; undefined: they
+     * chose none, and the answer is in the language of what they wrote. A chat turn's only: a group's is the sender's.
+     */
+    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,10 +1,22 @@
 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 { 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. */
 export declare function isMobile(clientPlatform: string): boolean;
+/**
+ * The path a message from Teams took: to the person's assistant, to a plain Claw session of their own (the old path, neither
+ * the assistant's nor a work item's), or to a review's turn. Logged so the worker's lines can be counted per path.
+ */
+export type TurnRoute = "assistant" | "legacy" | "review";
+/**
+ * The line for a turn started from Teams: where it came from and which path it took, never its words or any id. One line
+ * per turn: a message to the assistant or to a plain session is one turn, and a review request for several pull requests
+ * starts one review turn (and one line) for each.
+ */
+export declare function logTurnStarted(logger: Logger, clientPlatform: string, group: boolean, route: TurnRoute): void;
 /** A review the review service starts as a turn here (its item runs in Claw already; the turn only follows it). */
 export interface ReviewTurnStart {
     /** The work item Claw made for it ("" none: the turn makes a session of its own). */
@@ -41,6 +53,11 @@ export interface StartTurn {
     readonly sent?: string;
     readonly files?: readonly InboundFile[];
     readonly review?: ReviewTurnStart;
+    /**
+     * The person typed it in the chat (not a button, not a review): while the agent waits on a question card in this chat's
+     * session, it is the answer to that question and starts no turn.
+     */
+    readonly typed?: boolean;
 }
 /**
  * Starting and following a turn (the Python `Agent._start_turn`, `_queue_behind`, `_guarded`, `_record_session`,
@@ -55,7 +72,9 @@ 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;
     /** The turn goes to Claw now; its end is `done`. */
     private launch;
@@ -78,6 +97,8 @@ 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 the sender chose to be answered in, for a chat turn (a review's answer follows its request's language). */
+    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[];
 }
@@ -70,9 +71,11 @@ export interface TurnHooks {
     /**
      * An approval or question is about to be shown, as `envelope`: false when a card for it is already in a chat (the
      * notification got there first), and the turn then shows none. `expiresIn`: the seconds Brain waits for the answer.
+     * `questions`: a question's questions, as its event carried them (undefined for an approval).
      */
-    readonly onApproval?: (sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope) => boolean | undefined;
-    readonly onApprovalSent?: (sessionId: string, toolUseId: string) => void;
+    readonly onApproval?: (sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope, questions?: unknown) => boolean | undefined;
+    /** The card is in the chat; `cardId`: the chat's id of it, when the chat said it. */
+    readonly onApprovalSent?: (sessionId: string, toolUseId: string, cardId?: string) => void;
     readonly onApprovalUnsent?: (sessionId: string, toolUseId: string) => void;
     /** (session, "started" | "delivered" | "failed", Claw message id or ''). */
     readonly onTurn?: (sessionId: string, what: "started" | "delivered" | "failed", messageId: string) => void;
@@ -152,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;

package/dist/types/turn/engine/run-turn.d.ts

@@ -18,5 +18,7 @@ export interface TurnControls {
     /** The turn is cancelled: no live edit is sent after it, and the run's record is still kept. */
     readonly signal?: AbortSignal;
 }
+/** The id Claw gives a message it queued behind a running turn (`queuedMessageId`, claw/packages/api/src/tasks/chat-run.ts). */
+export declare const QUEUED_MESSAGE_PREFIX = "claw-pending-";
 /** Runs the turn and always leaves the user a message; `controls.onSession` records the session id. */
 export declare function runTurn(ctx: TurnContext, controls: TurnControls): Promise<void>;