@primusclaw/personal-agent 0.3.0 → 0.5.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/receipt.d.ts

@@ -54,6 +54,8 @@ export declare class Receipt {
     behind: string | undefined;
     unsent: boolean;
     private want;
+    /** Words of the reply were given to be shown (they may still be on their way to the channel). */
+    private wordsShown;
     private sender;
     private readonly closedWaiters;
     private readonly closer;
@@ -74,6 +76,8 @@ export declare class Receipt {
      * neither its turn nor the one in front of it, closes it as before.
      */
     answeredBy(turn: string | undefined): boolean;
+    /** Words of the reply are shown in it, or on their way to it: its turn has begun to answer. */
+    get answering(): boolean;
     /** Resolves when the receipt is closed (or being closed): what follows the turn stops then. */
     closed(): Promise<void>;
     /** Show `line` as the status, unless words of the reply are shown already. */

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

@@ -1,4 +1,5 @@
 import { type Lang } from "../locales/lang.js";
+import { type GroupContextKept } from "../locales/transparency.js";
 import { type Part } from "./registry.js";
 export declare const CURRENT_WORDS: Readonly<Record<Lang, string>>;
 /** A confirmation setting as help says it: [Chinese, English]. */
@@ -19,6 +20,8 @@ export interface HelpOptions {
     readonly lead?: string;
     readonly bot?: string;
     readonly understanding?: boolean;
+    /** The deployment keeps a group's recent messages as background (what the data statement then says it sees). */
+    readonly groupContext?: GroupContextKept;
 }
 /** The help for a chat, in `language` ("zh", or anything else for English). */
 export declare function renderHelp(language: string, options?: HelpOptions): string;

package/dist/types/config/settings.d.ts

@@ -38,7 +38,7 @@ export interface Settings {
     /** TEAMS_OBSERVE_USERS (lower-cased): who may turn on observing a group chat. */
     readonly observeUsers: ReadonlySet<string>;
     /**
-     * TEAMS_GROUP_CONTEXT_MESSAGES (30; 0 off), TEAMS_GROUP_CONTEXT_HOURS (4), TEAMS_GROUP_CONTEXT_CHARS (500): the recent
+     * TEAMS_GROUP_CONTEXT_MESSAGES (30; 0 off), TEAMS_GROUP_CONTEXT_HOURS (4), TEAMS_GROUP_CONTEXT_CHARS (500), TEAMS_GROUP_CONTEXT_GRANTED (off): the recent
      * messages of a group chat kept in memory as background for an @mention.
      */
     readonly groupContext: GroupContextSettings;

package/dist/types/group-context/buffer.d.ts

@@ -10,6 +10,7 @@
  * @mentions the bot, `background` gives what is kept, marked as untrusted history, for the turn to send before what they
  * wrote.
  */
+import type { GroupContextKept } from "../locales/transparency.js";
 import type { Clock } from "../ports/clock.js";
 import type { Logger } from "../ports/logger.js";
 import type { GroupContextRepository } from "../ports/store/group-context.js";
@@ -22,6 +23,12 @@ export interface GroupContextSettings {
     readonly maxAgeSeconds: number;
     /** The longest text kept of one message (code points). */
     readonly messageChars: number;
+    /**
+     * The deployment's chat app asks for the permission that delivers a group's other messages (Teams:
+     * ChatMessage.Read.Chat), so help says what is kept. Without it no such message arrives and help keeps the words
+     * "only the @mentions".
+     */
+    readonly granted: boolean;
 }
 export declare const DEFAULT_GROUP_CONTEXT: GroupContextSettings;
 /** The most chats kept at once: past it, the chat that heard nothing for longest is dropped. */
@@ -40,6 +47,11 @@ export declare class GroupContext {
     private readonly chats;
     constructor(deps: GroupContextDeps);
     get enabled(): boolean;
+    /**
+     * How much a chat keeps, as help says it: undefined when the deployment keeps nothing, its app is not granted the
+     * group's other messages (so none arrives), or `chatId` turned it off.
+     */
+    kept(chatId?: string): GroupContextKept | undefined;
     /** A group message not addressed to the bot: kept, never answered. */
     record(message: InboundMessage): void;
     /** The person edited a kept message: the new words replace the old (nothing when it is not kept). */

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

@@ -9,6 +9,11 @@ export declare const accountText: import("./catalog.js").Catalog<{
         email: string;
     }) => string;
     whoamiUnknown: string;
+    whoamiBound: (p: {
+        name: string;
+        email: string;
+    }) => string;
+    whoamiBoundUnknown: string;
     memoryUnreadable: (p: {
         page: string;
     }) => 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/transparency.d.ts

@@ -14,5 +14,26 @@ export declare const DATA_TITLE: Phrase;
 export declare const DATA_LINES: Readonly<Record<Lang, readonly string[]>>;
 /** Only where remote agents are on (a 1:1 chat): an attached chat's messages go to the person's own machine, not to PrimusClaw. */
 export declare const REMOTE_LINE: Phrase;
-/** The section of help about answers and data, in `lang`; `remote`: remote agents are on in this chat. */
-export declare function dataStatement(lang: string, remote?: boolean): string;
+/**
+ * How much of a group chat's recent messages the deployment keeps as background for an @mention (core's
+ * `GroupContext`, TEAMS_GROUP_CONTEXT_*), when that is on: the newest `messages`, none older than `hours`.
+ */
+export interface GroupContextKept {
+    readonly messages: number;
+    readonly hours: number;
+}
+/** "What I see" where a group's recent messages are kept: the group's @mentions are no longer all it sees. */
+export declare const SEES_LINE: Phrase;
+/**
+ * Only where the deployment keeps a group's recent messages (#725) and its app is granted them: what is kept, for how
+ * long, where it goes, and how to stop it; one short line each (help keeps every line short enough for a phone). The
+ * worker's buffer is memory only, but what it holds goes into the asker's session with an @mention (as the turn's
+ * quote), and a session is kept as the statement's "how long" says: so "not stored on their own", never "never stored".
+ * "May": a group whose mentions go to a remote agent (group-remote.ts) does not send them along.
+ */
+export declare function groupContextLines(lang: Lang, kept: GroupContextKept): readonly string[];
+/**
+ * The section of help about answers and data, in `lang`; `remote`: remote agents are on in this chat; `groupContext`:
+ * the deployment keeps a group's recent messages (absent: it does not, and a group's @mentions are all it sees).
+ */
+export declare function dataStatement(lang: string, remote?: boolean, groupContext?: GroupContextKept): string;

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

@@ -21,7 +21,11 @@ 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;
     /** The final message of a stream whose turn ended with nothing to say (it is never empty). */
     doneShort: string;
     /** What a failed turn says; the error itself, and its reference, go to the log only. */
@@ -46,7 +50,6 @@ export declare const turnEnglish: {
     readonly onlyTheAsker: " (only the person who asked can open it)";
     readonly wholeCutNote: "\n\n… (the rest did not fit in three messages)";
     readonly couldNotLoad: (name: string, count: number) => string;
-    readonly stopped: "Stopped.";
     readonly lostConnection: "I lost the connection to PrimusClaw before the task finished.";
     readonly openSessionLink: "Open the session";
     readonly keyRejected: "PrimusClaw rejected your linked key (it may have expired or been deleted). Send /unlink, then link again.";

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

@@ -336,8 +336,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/proactive/deliver.d.ts

@@ -4,9 +4,13 @@ import type { ProactiveDeps } from "./deps.js";
 import { type AnsweredInChat } from "./events.js";
 /** What the person asked, as the name of a run in its card and in the line before a lost turn's answer. */
 export declare const PROMPT_TITLE_MAX = 60;
+/** How many turns this process remembers that a say of theirs was delivered for (`Deliveries.answered`). */
+export declare const ANSWERED_TURNS_MAX = 512;
 export declare class Deliveries {
     private readonly deps;
     private readonly answeredInChat;
+    /** Turns a say of which (other than Claw's "on it" line) this process began to deliver, newest last. */
+    private readonly answered;
     constructor(deps: ProactiveDeps, answeredInChat: (event: JsonObject, now: number) => AnsweredInChat);
     /** Send the message for `event`; false when nothing was sent (an approval already in a chat, an event that says nothing). */
     send(userId: string, reference: JsonObject, event: JsonObject): Promise<boolean>;
@@ -23,6 +27,15 @@ export declare class Deliveries {
      * makes the message undelivered.
      */
     private sendSaid;
+    /**
+     * Claw's "on it" line for a turn that has already begun to answer: a say of the turn was delivered (or is being), or the
+     * receipt under the person's message is showing the reply's words. The line came late (it was decided before the answer,
+     * or the two crossed on the way here): it is dropped, never put in the receipt's place, where it would replace the words of
+     * a reply that is being written or close it as if it were the answer (2026-11-11 0.3.0 acceptance: a refusal streamed into
+     * the receipt, the line closed it as "收到，我看一下。", and the refusal came as a message of its own).
+     */
+    private lateTurnAck;
+    private noteAnswered;
     /** What the assistant said (or a work item that needs the person and was not said). */
     private sendSaidWords;
     /** The client locale of the message being handled ("" for a push or a sweep: Python CLIENT_LOCALE's default). */

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

@@ -76,8 +76,9 @@ export interface ProactiveDeps {
     readonly requestScope?: RequestScope;
     /**
      * After an assistant message whose turn was refused for want of a confirmed identity (`needs_identity`), in the person's own
-     * chat: the card that confirms it (`Credentials.identityAfterRefusal`), once per turn (`turn`: the message the turn answers,
-     * else the say's own id; a later say of the same turn replaces the first and carries the field too). Default: none.
+     * chat: the card that confirms it (`Credentials.identityAfterRefusal`: at most once per person in 24 hours, none once they
+     * confirmed), and never twice for one turn (`turn`: the message the turn answers, else the say's own id; a later say of the
+     * same turn replaces the first and carries the field too). Default: none.
      */
     readonly identityAfterRefusal?: (userId: string, conversation: Conversation, turn: string) => Promise<void>;
 }

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

@@ -1,4 +1,3 @@
-/** What the delivery of unasked messages adds to Claw's events, and reads of them, shared by its modules. */
 import type { JsonObject } from "../json.js";
 /** Epoch seconds, added by this worker to a held approval event. */
 export declare const EXPIRES_KEY = "_expires_at";
@@ -8,3 +7,12 @@ export declare const REMOTE_SAID = "remote.said";
 export declare function finishedAt(event: JsonObject, now: number): number;
 /** Whether this worker's own turn answered the run in the chat ("lost": a turn of an earlier process died answering it). */
 export type AnsweredInChat = "delivered" | "running" | "lost" | null;
+/**
+ * The id Claw gives its own "on it" line for the turn answering the person's message `messageId` ("收到，我看一下。", said by the
+ * server when the turn has said nothing by a deadline or starts a slow lookup): Claw's `lookupAckSayId`, a deterministic event id
+ * (`deterministicEventId("assistant.notice", <Claw user id>, "lookup_ack:<message id>")`, sha256 shaped as a uuid). The line carries
+ * no field of its own that says what it is; its id does.
+ */
+export declare function turnAckId(clawUserId: string, messageId: string): string;
+/** The turn whose "on it" line `event` is (`turnAckId`), or "" when it is not one. */
+export declare function turnAckOf(event: JsonObject): string;

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";
@@ -7,7 +9,17 @@ import type { CommandViews } from "./views.js";
 export declare class CredentialUnavailable extends Error {
     readonly name = "CredentialUnavailable";
 }
+/** The identity card after a refused answer goes to a person at most this often (`identityAfterRefusal`). */
+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`).
@@ -28,8 +40,10 @@ export declare class Credentials {
     /**
      * After an answer of the assistant that was refused for want of a confirmed identity (`needs_identity`: a person whose chats
      * run on their key because they never confirmed it asked for something only they may do, such as a review as them): the card
-     * that confirms it, unless the person has confirmed by now. Nothing when chats do not run on the exchange, or it cannot be
-     * asked. Never before that: connecting a machine and the rest of what a key may do are not held behind it.
+     * that confirms it, at most once per person in IDENTITY_CARD_INTERVAL_SECONDS (the time it was last sent is kept in the
+     * store, so a restart or another replica does not send it again), and never once the person has confirmed. Nothing when
+     * chats do not run on the exchange, or it cannot be asked; a card that was not sent leaves the allowance unspent. Never
+     * before such an answer: connecting a machine and the rest of what a key may do are not held behind it.
      */
     identityAfterRefusal(chat: Chat): Promise<boolean>;
     /** The binding card with `lead`; false (nothing sent) when the identity service gives no link: a key's owner is not sent the `/link` steps. */

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

@@ -2,6 +2,7 @@ import type { GithubConnection } from "../claw/model.js";
 import type { JsonObject } from "../json.js";
 import type { KeyOwner } from "../plugins/identity-lookup.js";
 import type { Lang } from "../locales/lang.js";
+import type { GroupContextKept } from "../locales/transparency.js";
 import type { Conversation, InboundFile, InboundMessage, OutMessage, UserRef } from "../ports/surface.js";
 /**
  * What the router asks of the features it hands messages to. Each is implemented by the feature's own module (the
@@ -156,6 +157,8 @@ export interface GroupHistory {
     record(message: InboundMessage): void;
     /** The chat's kept messages as background for a turn ("" none). */
     background(chatId: string): string;
+    /** How much a chat keeps, for help to say (undefined: nothing arrives or is kept, or `chatId` turned it off). */
+    kept(chatId?: string): GroupContextKept | undefined;
 }
 /** The review service's part in the chat (Python `github_review.GithubReview` and `github_connect.GithubConnect`). */
 export interface GithubChat {

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`):

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-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`,
@@ -56,6 +73,8 @@ export declare class TurnStarter {
     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>;
+    /** 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;

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

@@ -21,6 +21,8 @@ export interface BindingCardView {
     /** A first sentence ("" none). */
     readonly lead: string;
     readonly notice: string;
+    /** The language of its title, body and buttons: the person's. */
+    readonly lang: Lang;
 }
 /** A group member who has not connected: addressed to them, one button only they can use. */
 export interface OnboardingCardView {
@@ -94,7 +96,8 @@ export declare class CommandViews {
     readonly note: NoteFactory;
     constructor(bot: string, publicBaseUrl: string, note: NoteFactory);
     link(who: string): OutMessage;
-    binding(confirmUrl: string, lead?: string): OutMessage;
+    /** The binding card in the person's language `lang` (its title, body, buttons and notice; `lead` is the caller's). */
+    binding(confirmUrl: string, lead?: string, lang?: Lang): OutMessage;
     onboarding(member: {
         name: string;
         channelUserId: string;

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

@@ -70,9 +70,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;

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>;

package/dist/types/turn/progress/status-message.d.ts

@@ -54,6 +54,8 @@ export declare class StatusMessage<S> {
     private opening;
     private expiry;
     private again;
+    /** The stream being closed because a card waits for the person (`awaitingChoice`). */
+    private choice;
     private preparingTimer;
     private lastText;
     private lastAt;
@@ -80,6 +82,24 @@ export declare class StatusMessage<S> {
     private statusLines;
     /** Close the stream with STILL_WORKING before the chat's limit; the answer, whenever it comes, is a message of its own. */
     private closeInTime;
+    /**
+     * Close the open stream with `line` (after the agent's words in the bubble) while the turn goes on; the answer, whenever it comes, is
+     * a message of its own. Nothing more is sent to the stream once this has begun.
+     */
+    private closeEarly;
+    /**
+     * A card now waits for the person (a question of the agent): it is their turn, so the floating status must not go on
+     * saying "Thinking…" until the chat's limit. An open stream is closed at once with AWAITING_CHOICE, and the answer comes
+     * as a message of its own, as after the limit. Without a stream (the progress message) nothing changes: it has no
+     * spinner. Never fails the turn.
+     */
+    awaitingChoice(): void;
+    /**
+     * Claw queued the message behind a turn it is still running: `notice` closes the stream at once, so it does not say
+     * "Thinking…" for the whole wait. The answer comes as a message of its own, as after the limit. When the stream did not open
+     * after all, `notice` is said as a message. False when there is no stream: the caller says it. Never fails the turn.
+     */
+    queued(notice: string): boolean;
     /** The chat's id of the posted message; undefined when the post failed or its id never came (nothing is edited then). */
     private messageId;
     /**

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

@@ -24,8 +24,8 @@ export interface TurnApprovals {
      * False when a card for this approval is already in a chat: the turn then shows none. `userId`: the person the turn is for,
      * whose approval it is (Python `store.save_approval(sender.aad_id, ...)`).
      */
-    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;
 }
 /** What a review turn adds to a chat turn (the review service fills it in). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primusclaw/personal-agent",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The personal agent's channel-neutral core: domain logic, ports and plugin interfaces.",
   "license": "MIT",
   "repository": {