@primusclaw/personal-agent 0.1.1 → 0.3.0

package/dist/types/protocol/remote-agents.d.ts

@@ -155,6 +155,40 @@ export interface RemoteSessionNew {
     takeover: boolean;
 }
 export declare function parseSessionNew(body: unknown): Parsed<RemoteSessionNew>;
+/**
+ * Approvals a terminal asks for, carried to the phone (`POST /v1/remote-agents/connectors/:cid/terminal-sessions`).
+ *
+ * A coding agent its person started in their own terminal asks there before it runs a command, edits a file, leaves plan mode or
+ * puts a multiple-choice question. A connector whose hook sees such a prompt opens (or finds) one session per terminal conversation
+ * (`ref`, the agent's own conversation id) and posts each prompt on it as a `permissionRequest`, with
+ * `data.origin` {@link REMOTE_ORIGIN_TERMINAL_HOOK}; the owner answers it as any other, with a `decision`. The terminal keeps its own
+ * prompt: whichever answer comes first is the one the agent takes, and the connector says which (`permission_resolved.by`).
+ *
+ * Such a session carries nothing else: no prompt, no turn, no mode. It is not one of the sessions a user opens, so it neither counts
+ * against {@link REMOTE_AGENT_LIMITS.maxActiveSessionsPerUser} nor is closed to make room for one.
+ */
+export declare const REMOTE_ORIGIN_TERMINAL_HOOK = "terminal_hook";
+/** The only commands a terminal-hook session takes: an answer, and closing it. */
+export declare const TERMINAL_HOOK_COMMANDS: readonly RemoteCommandType[];
+export declare const TERMINAL_SESSION_LIMITS: {
+    /** Terminal-hook sessions one user may open per minute, across their machines (a new terminal conversation opens one). */
+    readonly opensPerMinute: 30;
+    /** Characters of a session's title (the conversation's name, or the start of its first prompt). */
+    readonly maxTitleChars: 80;
+};
+export interface RemoteTerminalSessionOpen {
+    agent_id: string;
+    /** The agent's own id of the conversation open in the terminal. */
+    ref: string;
+    cwd: string;
+    /** The conversation's name, or the start of its first prompt; empty when the connector has neither. */
+    title: string;
+}
+export declare function parseTerminalSessionOpen(body: unknown): Parsed<RemoteTerminalSessionOpen>;
+/** The owner's switch for approvals from terminals (`GET`/`PUT /v1/remote-agents/approvals`). On unless they turned it off. */
+export declare function parseApprovalsSetting(body: unknown): Parsed<{
+    enabled: boolean;
+}>;
 /**
  * Hiding conversations of a machine from its owner's lists (`POST /v1/remote-agents/connectors/:cid/hidden`), and the
  * listing that leaves them out (`GET /v1/remote-agents/connectors`, `?hidden=include` to list them too). Nothing on the

package/dist/types/remote/approvals-command.d.ts

@@ -0,0 +1,8 @@
+import type { ClawRemoteAgentsPort } from "../ports/claw/remote-agents.js";
+import type { CommandHandler, CommandRoute } from "../ports/routing.js";
+export declare class TerminalApprovalsCommand implements CommandHandler {
+    private readonly claw;
+    readonly name = "approvals";
+    constructor(claw: Pick<ClawRemoteAgentsPort, "approvals" | "setApprovals">);
+    run(route: CommandRoute, args: string): Promise<boolean>;
+}

package/dist/types/remote/chats.d.ts

@@ -20,6 +20,23 @@ export interface RemoteTurn {
     /** Nothing runs it any more (or nothing ever did): a Stop card's press for it stops nothing. */
     readonly ended: boolean;
 }
+/**
+ * A message sent to the attached session while a turn of the chat still ran. Claw keeps it in order and the machine runs it once the
+ * turn in front has ended (the connector queues it, as Claude Code queues what is typed while it works); its own turn is read right
+ * after the one in front (`TurnRunner`).
+ */
+export interface QueuedPrompt {
+    /** The channel's id of the person's message ("" none): a redelivered message queues nothing more. */
+    readonly messageId: string;
+    /** Claw's sequence number of the prompt (a refusal of it names it); undefined while its send is on its way, or none was given. */
+    readonly cmdSeq: number | undefined;
+    /** Start reading its turn: false when it cannot be (the chat is no longer attached to that session). */
+    start(): boolean;
+}
+/** At most this many messages wait behind a running turn (the connector refuses more: `too_many_queued_prompts`). */
+export declare const QUEUED_PROMPTS_MAX = 5;
+/** Refusals of prompts no queued message could be matched to yet, kept per chat for the send that is still on its way. */
+export declare const REFUSALS_KEPT = 20;
 /** A turn about to be watched (its task is set right after). */
 export declare function newTurn(): RemoteTurn;
 /** The confirmation card for taking over a conversation a terminal has open: only its own Take over carries the ticket. */
@@ -37,6 +54,10 @@ export declare class ChatRegistry {
     /** Chats `forget` was called for: nothing follows them until they attach again. */
     readonly unlinked: Set<string>;
     readonly turns: Map<string, RemoteTurn>;
+    /** The messages sent while the chat's turn ran, oldest first: each one's turn is read after the one in front. */
+    private readonly queuedPrompts;
+    /** Prompt refusals (Claw's number -> the reason) that came before any queued message had that number. */
+    private readonly refusals;
     /** A short watch (`/agent new` waiting for the agent, `/agent mode` for its answer). */
     readonly watchers: Map<string, Task>;
     /** Whether the agent of the attached session starts in a mode that does not ask (its connector's report). */
@@ -48,6 +69,25 @@ export declare class ChatRegistry {
     private readonly readOnlyKnown;
     private readonly terminalInput;
     private readonly tickets;
+    /** How many messages wait behind the chat's running turn. */
+    queuedCount(chatKey: string): number;
+    enqueue(chatKey: string, prompt: QueuedPrompt): void;
+    /** The oldest message waiting, taken off the queue. */
+    takeQueued(chatKey: string): QueuedPrompt | undefined;
+    /** Whether a message with this channel id already waits in the chat's queue. */
+    queuedMessage(chatKey: string, messageId: string): boolean;
+    /** A prompt refusal no queued message has the number of yet (its send has not answered): kept for that send. */
+    noteRefusal(chatKey: string, cmdSeq: number, reason: string): void;
+    /** The reason the machine refused the prompt `cmdSeq` before its send answered, taken (undefined: not refused). */
+    takeRefusal(chatKey: string, cmdSeq: number): string | undefined;
+    /** Whether `prompt` still waits in the chat's queue. */
+    isQueued(chatKey: string, prompt: QueuedPrompt): boolean;
+    /** Take `prompt` off the queue (its send failed); false when it is not there (its turn was started meanwhile). */
+    removeQueued(chatKey: string, prompt: QueuedPrompt): boolean;
+    /** The waiting message Claw numbered `cmdSeq` (refused before it ran), taken off the queue. */
+    takeQueuedSeq(chatKey: string, cmdSeq: number): QueuedPrompt | undefined;
+    /** Every waiting message is given up (a stop drops them on the machine too); how many there were. */
+    dropQueued(chatKey: string): number;
     watching(chatKey: string): boolean;
     /** The chat's session only watches a conversation open in a terminal (read-only). */
     watches(chatKey: string, sessionId: string | null): boolean;

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

@@ -29,13 +29,16 @@ export interface RemoteStep {
     readonly started: boolean;
     /** The turn is over. */
     readonly finished: boolean;
+    /** Claw's number of the prompt whose turn ended (a `turn_end` that names it), null when it does not say. */
+    readonly endsSeq: number | null;
     readonly stopReason: string;
     /** The session ended: the reason, "" when none was given. */
     readonly closed: string | null;
-    /** A command the connector refused. */
+    /** A command the connector refused (`cmdSeq`: Claw's number of it, null when the connector did not name it). */
     readonly rejected: {
         readonly type: string;
         readonly reason: string;
+        readonly cmdSeq: number | null;
     } | null;
     /** An event of history the agent replayed: never shown as new. */
     readonly replay: boolean;

package/dist/types/remote/follow/control.d.ts

@@ -24,10 +24,20 @@ export declare class FollowControl {
     drop(chatKey: string): void;
     /** Stop the reader before a message goes to the agent, with what it has read delivered: true when there was one to stop. */
     stop(chatKey: string): Promise<boolean>;
+    /**
+     * A conversation open in a terminal, watched or typed into: what is typed there is answered there, with no turn of the phone's to
+     * end it, so its reply is told after a few quiet seconds, as a watch's is. With the half-minute of a session of the phone's own it
+     * came after the person had left (2026-11-11 guide re-check: nothing within 20 s, although the card says replies show up here).
+     * Read each time they are used: a worker that restarted learns only after its reader started whether the session is a terminal's
+     * (`resume`).
+     */
+    private timingsOf;
     /** The chat leaves its session. */
     detach(chatKey: string): void;
     /** Follow every chat that is attached: a worker that starts delivers what its agents said while it was away, once. */
     resume(): void;
+    /** What this process forgot in a restart: whether the chat's session only watches or types into a terminal (its timings). */
+    private learn;
     shutdown(): void;
     /**
      * TEAMS_DIRECT_CHAT is on for this person: an attachment that still has the session card as its window is moved to the chat,

package/dist/types/remote/prompt.d.ts

@@ -1,10 +1,10 @@
 import { type Conversation } from "../ports/surface.js";
 import type { StatusBoard } from "./board.js";
-import type { RemoteTurn } from "./chats.js";
 import type { RemoteContext } from "./context.js";
 import type { Provider } from "./ended.js";
 import type { FollowControl } from "./follow/control.js";
 import type { SessionStarts } from "./sessions.js";
+import { type RemoteTurn } from "./chats.js";
 import { type ChatState } from "./state.js";
 import type { TurnRunner } from "./turns/runner.js";
 import type { Watches } from "./watches.js";
@@ -35,9 +35,19 @@ export declare class Prompts {
     private say;
     /** Plain text from a chat that is attached: it is the agent's, not the assistant's. */
     prompt(p: Prompt): Promise<void>;
+    /**
+     * A message while the chat's turn runs: sent to the session now (Claw keeps it in order; the machine runs it once the turn in
+     * front has ended), and its turn is read after that one. It is put in the queue before it is sent: the turn in front may end
+     * while the send is on its way, and its turn must be read from where that one ended, not by the follower. Refused only past what
+     * the machine queues.
+     */
+    private queueBehind;
     /** The terminal is using the session: what is typed here is answered, never sent. */
     private watched;
-    /** The prompt to Claw; false (and the person told why) when it did not go. */
+    /**
+     * The prompt to Claw, with Claw's number of it (`duplicate`: Claw had this message already, a redelivery); false (and the person
+     * told why) when it did not go.
+     */
     private send;
     private failure;
     private started;
@@ -54,6 +64,8 @@ export declare class Prompts {
     stop(chatKey: string, key: string, to: Conversation, only?: RemoteTurn): Promise<boolean>;
     /** The Stop card's turn is still the one running for the chat, and the chat is still attached. */
     private stillOn;
+    /** What a stop says of the messages it gave up ("" none). */
+    private droppedLine;
     private cancel;
     /** A turn nobody reads any more is not open: what the agent says from here on is the follower's. */
     private closeTurn;

package/dist/types/remote/state.d.ts

@@ -37,7 +37,10 @@ export declare class ChatState {
     /** The view when the chat has one, without making one. */
     existingView(chatKey: string): WindowView | undefined;
     forgetView(chatKey: string): void;
-    /** The approvals the chat's session waits for, as the window shows them (none in a group: those go to the binder's 1:1). */
+    /**
+     * The approvals the chat's session waits for, as the window shows them (none in a group: those go to the binder's 1:1). A
+     * question a terminal asks is never among them: the window shows a tool and buttons, not the request, and it has its own card.
+     */
     approvalsOf(chatKey: string, state: RemoteState): RemotePermission[];
     /** The person's time zone (IANA), the default when theirs is not one. */
     zone(chatKey: string): string;

package/dist/types/remote/terminal-asks.d.ts

@@ -0,0 +1,9 @@
+/** What is kept of a question a terminal asks (a connector's approval hooks), for the clicks on its card. */
+import type { RemotePermission } from "../ports/store/remote.js";
+import type { PermissionOption } from "./options.js";
+/** The field of a kept terminal ask that says its card showed the request whole (set by this worker, never by Claw). */
+export declare const SHOWN_WHOLE = "clawy_shown_whole";
+/** Whether `perm` is a question a terminal asks. */
+export declare function isTerminalPermission(perm: RemotePermission): boolean;
+/** Whether `option` may be chosen for `perm`: a terminal's question not shown whole may only be turned down from here. */
+export declare function mayChoose(perm: RemotePermission, option: PermissionOption): boolean;

package/dist/types/remote/turn-state.d.ts

@@ -8,6 +8,11 @@ import { type RemoteStep } from "./events.js";
  */
 export declare class RemoteTurnState {
     private readonly errors;
+    /**
+     * Claw's number of the prompt this turn answers, read at each event (a queued message's reader may start before its send has
+     * answered): the connector's refusal of it ends the turn (no `turn_end` follows one).
+     */
+    private readonly seqOf;
     /** Event ids already seen, oldest first (at most SEEN_KEPT). */
     readonly seen: Set<string>;
     /** Message text, one entry per stretch between tool calls (at most SEGMENTS_KEPT). */
@@ -17,8 +22,18 @@ export declare class RemoteTurnState {
     closed: string | null;
     note: string | null;
     private toolSinceText;
-    constructor(errors: PublicErrors);
+    constructor(errors: PublicErrors, 
+    /**
+     * Claw's number of the prompt this turn answers, read at each event (a queued message's reader may start before its send has
+     * answered): the connector's refusal of it ends the turn (no `turn_end` follows one).
+     */
+    seqOf?: () => number | undefined);
     feed(event: SseEvent): RemoteStep;
+    /** A turn end that names another prompt than this turn's. */
+    private othersEnd;
+    /** The connector refused the prompt this turn answers. */
+    private refusedOwn;
+    private end;
     /** The agent's last piece of text, stripped. */
     get answer(): string;
     /** The answer so far, and the text is forgotten (the event ids already seen are not): what a reader that goes on after a

package/dist/types/remote/turns/chat-turn.d.ts

@@ -19,7 +19,10 @@ export declare class RemoteStatusPolicy implements StatusPolicy<RemoteStep> {
     readonly view: LiveViewLike;
     constructor(live: RemoteLive, cutError: (text: string) => string, signer: Signer | null);
     applyStep(step: RemoteStep): boolean;
-    /** Everything the agent has written this turn, as it is shown (under its head, with a signer). */
+    /**
+     * Everything the agent has written this turn, as it is shown (under its head, with a signer). `settled`: only what the rest of the
+     * text can no longer change, for the bubble while the agent still writes (`streamable`).
+     */
     private saidText;
     streamable(streamed: string): string;
     /**
@@ -29,6 +32,14 @@ export declare class RemoteStatusPolicy implements StatusPolicy<RemoteStep> {
      */
     finishStream(input: StreamFinishInput): StreamFinish | undefined;
 }
+/**
+ * `text` up to a code span still being written: on its last line (where the agent is still writing; a span never crosses a line), the
+ * first run of backticks that no later run of the same length closes, and what follows it. Streamed, such a backtick is shown as a
+ * look-alike (`inertAnswer`: one the rich text cannot pair), and once the agent closes the span it is a backtick again: the text no
+ * longer begins with what the bubble shows, so the bubble ends on that lone character and the answer follows as a message of its own
+ * (2026-11-11 guide re-check: a reply that began with `` `hook.txt` `` ended its bubble on "ˋ"). Escaped backticks open nothing.
+ */
+export declare function withoutOpenCode(text: string): string;
 /** The turn shown in the chat (a stream, else a progress message), as a `TurnDisplay`. */
 export declare class ChatTurn implements TurnDisplay {
     private readonly surface;

package/dist/types/remote/turns/display.d.ts

@@ -10,6 +10,8 @@ export interface TurnDisplay {
     close(hard?: boolean): void;
     /** The answer: `parts` in order, the suggested `replies` under the last. */
     finish(parts: readonly string[], options: FinishWith): Promise<void>;
+    /** After `finish`, when the turn of a queued message follows at once: what this turn showed must stay readable (optional). */
+    handOver?(): Promise<void>;
 }
 export interface FinishWith {
     /** What the agent wrote (the AI label). */

package/dist/types/remote/turns/runner.d.ts

@@ -25,6 +25,8 @@ export interface TurnRequest {
     readonly state: RemoteState;
     /** The person's message the turn answers (a stream answers it); undefined: shown by a progress message. */
     readonly replyTo: string | undefined;
+    /** Claw's number of the prompt the turn answers, read as events come (undefined: not known, any turn end ends it). */
+    readonly cmdSeq?: (() => number | undefined) | undefined;
 }
 export declare class TurnRunner {
     private readonly ctx;
@@ -37,8 +39,16 @@ export declare class TurnRunner {
     constructor(ctx: RemoteContext, state: ChatState, board: StatusBoard, follow: FollowControl, ended: EndedWords, show: (chatKey: string, sid: string, request: Readonly<Record<string, unknown>>, to: Conversation) => Promise<void>, displayFor: DisplayFor);
     /** Watch the turn that is open on the chat's session. */
     start(request: TurnRequest): void;
+    /** Stop reading the chat's turn; the messages waiting behind it are given up too (nothing will read their turns). */
     cancel(chatKey: string): void;
+    /** Stop reading the chat's turn only (it will have none): the turn of the next queued message, if any, is read instead. */
+    stopReading(chatKey: string): void;
     private guarded;
+    /**
+     * The turn is over: the turn of the oldest message sent behind it is read next (it runs on the machine now), or, with none
+     * waiting, what the agent says next is followed from where the turn ended.
+     */
+    private over;
     private display;
     private run;
     /** The turn could not be read to its end: the session is gone, Claw refused, or the connection was lost. */
@@ -51,5 +61,10 @@ export declare class TurnRunner {
     /** One stream, read until it ends or the turn does. */
     private readStream;
     private apply;
+    /**
+     * A message waiting behind this turn was refused on the machine before it ran: it waits no more, and the person is told. One whose
+     * send has not answered yet has no number to match: the refusal is kept for that send (`Prompts.queueBehind`).
+     */
+    private queuedRefused;
     private sayRecovered;
 }

package/dist/types/remote/turns/window-turn.d.ts

@@ -3,7 +3,7 @@
  * the card's output (an edit at most every EDIT_SECONDS), the step it runs and a message waiting for the terminal are its state,
  * and the end of the turn refreshes it (posted again at the bottom: a phone may not redraw an edit). Nothing else is posted.
  */
-import type { Conversation } from "../../ports/surface.js";
+import { type Conversation } from "../../ports/surface.js";
 import { type RemoteStep } from "../events.js";
 import type { StatusBoard } from "../board.js";
 import type { ChatState } from "../state.js";
@@ -26,4 +26,8 @@ export declare class WindowTurn implements TurnDisplay {
     close(): void;
     /** (the window has no labels or replies: the options are the chat's) */
     finish(parts: readonly string[]): Promise<void>;
+    /** The turn of a queued message follows at once and takes the card over: this turn's answer is posted to the chat to stay. */
+    handOver(): Promise<void>;
 }
+/** A finished answer the next queued turn takes the card from is posted to the chat up to this many characters. */
+export declare const HANDED_OVER_MAX = 3500;

package/dist/types/remote-view/index.d.ts

@@ -8,6 +8,7 @@ import type { DisconnectView, MachineChoiceView, ModeView, TakeoverView } from "
 import type { DecidedView, PermissionView, RemoteAskView } from "./permission-view.js";
 import type { SessionsView } from "./sessions-view.js";
 import type { StatusView } from "./status-view.js";
+import type { TerminalAskView } from "./terminal-ask-view.js";
 import type { HiddenView } from "./hidden-view.js";
 import type { WindowCardView } from "./window-view.js";
 export * from "./agents-view.js";
@@ -18,6 +19,7 @@ export * from "./machine-views.js";
 export * from "./permission-view.js";
 export * from "./sessions-view.js";
 export * from "./status-view.js";
+export * from "./terminal-ask-view.js";
 export * from "./window-view.js";
 export { remoteHealthText, remoteOffText, remoteQueuedText, remoteStopText, remoteText } from "../locales/remote.js";
 export { remoteWindowCardText } from "../locales/remote-window-card.js";
@@ -28,6 +30,7 @@ declare module "../ports/surface.js" {
         remoteStatus: StatusView;
         remotePermission: PermissionView;
         remoteAsk: RemoteAskView;
+        terminalAsk: TerminalAskView;
         remoteDecided: DecidedView;
         remoteDisconnect: DisconnectView;
         remoteTakeover: TakeoverView;

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

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ *
+ * 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
+ * options that turn it down, and says to approve it at the terminal. So does one the card cannot show as it is: a credential
+ * 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 { DecisionButton } from "../remote/actions.js";
+import { type PermissionOption } from "../remote/options.js";
+import type { Reported } from "../remote/reported.js";
+/**
+ * The most of a request's content a card shows, in characters. A Teams card carries about 28 KB; the content Claw sends is at
+ * most 16 KiB of JSON, and what is shown of it (unescaped, without the JSON's quoting) is no longer.
+ */
+export declare const TERMINAL_CONTENT_MAX = 16000;
+/** The most bytes of rendered content (as the card's JSON carries it) a card holds, leaving room under Teams' ~28 KB for the rest. */
+export declare const TERMINAL_CARD_BYTES = 20000;
+/** The content budget of the cut-short card a channel falls back to. */
+export declare const TERMINAL_FALLBACK_BYTES = 4000;
+/** One piece of a terminal request's content. `code`: shown as it is, in a fixed-width font; `words`: markdown kept, links not. */
+export type TerminalSection = {
+    readonly type: "line";
+    readonly text: string;
+} | {
+    readonly type: "code";
+    readonly text: string;
+} | {
+    readonly type: "words";
+    readonly text: string;
+} | {
+    readonly type: "option";
+    readonly label: string;
+    readonly description: string;
+};
+export interface TerminalAskView {
+    readonly lang: Lang;
+    readonly title: string;
+    /** Whose agent asks, on which machine, in which project. */
+    readonly who: string;
+    /** What it asks, before the content ("wants to run:"). */
+    readonly asks: string;
+    readonly sections: readonly TerminalSection[];
+    readonly notes: readonly string[];
+    readonly buttons: readonly DecisionButton[];
+    /** The whole request is on the card (else only the options that turn it down are). */
+    readonly complete: boolean;
+    /**
+     * The same card cut short (content within TERMINAL_FALLBACK_BYTES, only the options that turn it down, no "always" notes): what
+     * a channel sends when the card as built is larger than it can carry. Absent on the fallback itself.
+     */
+    readonly fallback?: TerminalAskView;
+}
+export interface TerminalAsk {
+    /** `remote.ask` as Claw relayed it: `action_id`, `tool`, `kind`, `input`, `question_index`, `question_count`. */
+    readonly ask: Reported;
+    readonly options: readonly PermissionOption[];
+    readonly sessionId: string;
+    readonly machine: string;
+    readonly agent: string;
+}
+/** 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. */
+export declare function terminalAskView(input: TerminalAsk, lang?: Lang): TerminalAskView;

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

@@ -16,9 +16,11 @@ export declare class SessionCommands {
     /**
      * `/stop` of the turn on the chat's own session (not a remote agent's, not the assistant's). `only`: stop only while that
      * turn is the one running (a Stop card's turn), checked with no wait before the interrupt goes; false when it is not, and
-     * nothing was said or stopped.
+     * nothing was said or stopped. `/stop` (no `only`) also gives up the messages queued behind the running turn, and says so.
      */
     stopTurn(chat: Chat, key: string, scope?: string, only?: ActiveTurn): Promise<boolean>;
+    /** The chat's turn Claw runs now: the first one not stopped already (one queued behind a stopped turn goes at once). */
+    private running;
     private interrupt;
     /**
      * The five sessions this chat used last, a card each with Show here. No session is shown on the worker's word alone: each

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

@@ -25,6 +25,15 @@ export declare class Credentials {
     get onExchange(): boolean;
     /** What to call Claw with for this person, or undefined after they were told what to do (`ask`). */
     credential(chat: Chat, ask?: boolean): Promise<string | undefined>;
+    /**
+     * 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.
+     */
+    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. */
+    private sendIdentityCard;
     /** A fresh credential per call when chats run on exchanged tokens (they expire); undefined: the key as it is. */
     provider(userId: string, key: string): CredentialProvider;
     /** The person's exchanged token, else `fallback` (a turn can outlive a 10-minute token: each Claw call asks again). */

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

@@ -13,7 +13,7 @@ import type { StorePort } from "../ports/store/index.js";
 import type { ConversationRef, OutMessage, Surface } from "../ports/surface.js";
 import type { JsonObject } from "../json.js";
 import type { SecurityEventName } from "../observability/security-events.js";
-import type { AssistantChat, ChannelContextBuilder, ConnectionsText, GithubChat, MessageText, NoteFactory, Observing, RemoteChat, ReviewStopReader, StopCards, Subscriptions } from "./features.js";
+import type { AssistantChat, ChannelContextBuilder, ConnectionsText, GithubChat, GroupHistory, MessageText, NoteFactory, Observing, RemoteChat, ReviewStopReader, StopCards, Subscriptions } from "./features.js";
 import type { TurnRunner } from "./turn-runner.js";
 /** What a deployment sets for the router (the Python `Agent.__init__` arguments that are settings). */
 export interface RouterConfig {
@@ -97,6 +97,8 @@ export interface RouterDeps {
     readonly stopCards: StopCards;
     readonly proactive: ProactiveHold;
     readonly observing: Observing;
+    /** The recent messages of group chats, as background when the bot is @mentioned there. */
+    readonly groupHistory: GroupHistory;
     readonly github: GithubChat | undefined;
     /** The review-stop words of a group (with the review service on). */
     readonly reviewStop: ReviewStopReader | undefined;

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

@@ -52,9 +52,9 @@ export interface AssistantChat {
     board(userId: string, credential: string, conversation: Conversation): Promise<void>;
     /**
      * What the assistant is doing this moment is stopped. `onlyMessage`: only while Claw's running turn answers that
-     * message; false, with nothing said or stopped, when it does not.
+     * message; false, with nothing said or stopped, when it does not. What is said is in `lang` (the chat's).
      */
-    stop(userId: string, credential: string, conversation: Conversation, onlyMessage?: string): Promise<boolean>;
+    stop(userId: string, credential: string, conversation: Conversation, onlyMessage?: string, lang?: Lang): Promise<boolean>;
     /** Forget what is kept for the person (they unlinked). */
     forget(userId: string): void;
     /** True when the assistant took the message. */
@@ -134,7 +134,8 @@ export interface RemoteChat {
 }
 /** The person's notification subscription in Claw (Python `subscriptions.Subscriptions`); undefined when notifications are off. */
 export interface Subscriptions {
-    ensure(userId: string): Promise<void>;
+    /** Made or mended with `credential` when given (a person with no link: their exchanged token), else the linked key. */
+    ensure(userId: string, credential?: string): Promise<void>;
     /** Before the key is revoked: Claw needs it to delete the subscription. */
     remove(userId: string, key: string): Promise<void>;
 }
@@ -146,6 +147,16 @@ export interface Observing {
     /** The suggestions the observed groups make for the person (`/board`). */
     board(userId: string, credential: string, conversation: Conversation): Promise<void>;
 }
+/**
+ * The recent messages of a group chat, as background when the bot is @mentioned there (`group-context/buffer.ts`). Fed
+ * only by group messages that do not address the bot, which a channel delivers only where the chat allowed it.
+ */
+export interface GroupHistory {
+    /** A group message not addressed to the bot: kept in memory, never answered. */
+    record(message: InboundMessage): void;
+    /** The chat's kept messages as background for a turn ("" none). */
+    background(chatId: string): string;
+}
 /** The review service's part in the chat (Python `github_review.GithubReview` and `github_connect.GithubConnect`). */
 export interface GithubChat {
     /** Which channel id is whose, for reading a mention in a group. */

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

@@ -29,6 +29,8 @@ export declare class GroupRouter {
     /** A command of a 1:1 chat (`/agent attach|detach` binds the group: it stays the group's). */
     private oneToOneOnly;
     private withKey;
+    /** The chat's recent messages, as untrusted background, before what the person quoted (either may be ""). */
+    private withHistory;
     /** Which account, in a group: never the sender's email. */
     private whoami;
     /**

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

@@ -15,8 +15,21 @@ export declare class PersonalRouter {
     private readonly text;
     private readonly stopPress;
     private readonly showHere;
+    /** A person's bound id is read and kept one message at a time, so a late lookup of an earlier token never wins. */
+    private readonly boundLock;
     constructor(ctx: RouterContext, sets: CommandSets, text: PersonalText);
     route(event: InboundMessage | InboundAction, chat: Chat): Promise<void>;
+    /**
+     * A person with no link whose chats run on an exchanged token (bound at the identity service): their Claw user id is
+     * read with the token and their subscription made with it, as a link's are, so their 1:1 chat reaches the assistant
+     * from this message on (the assistant reaches only a person whose Claw user id and subscription it knows).
+     *
+     * The id is read again whenever the token is not the one it was read with (tokens last minutes, so at most once a token):
+     * a person who rebinds to another account is followed to it, and one no longer bound is forgotten, so the assistant
+     * never keeps answering for an account the person no longer holds (nor for one whose owner a new token cannot tell yet).
+     * A subscription is made or mended only with a token whose owner is the id kept.
+     */
+    private reachBound;
     /** Linked before the Claw user id was kept: it is read now. */
     private backfill;
     private message;

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

@@ -1,15 +1,19 @@
 /**
  * The turns this worker follows, per chat (the Python `Agent._turns`, `ActiveTurn`, `_queue_behind`, `_drop_turn`,
- * `_item_stopped`). A chat has the turn Claw runs and at most one queued behind it; a review for a colleague is kept
- * under a key of its own per pull request, so it neither waits for nor blocks the asker's chat turn.
+ * `_item_stopped`). A chat has the turn Claw runs and up to `QUEUED_TURNS_MAX` queued behind it, in the order they were sent; a
+ * review for a colleague is kept under a key of its own per pull request, so it neither waits for nor blocks the asker's chat turn.
  */
 import type { Clock } from "../ports/clock.js";
+/** The messages that may wait behind a chat's running turn (as many as an attached agent's chat queues). */
+export declare const QUEUED_TURNS_MAX = 5;
 /** A signal that is set once: what a message queued behind a turn waits for. */
 export declare class Latch {
     private done;
     private readonly waiters;
     get isSet(): boolean;
     set(): void;
+    /** Settles once it is set. */
+    whenSet(): Promise<void>;
     /** True when it was set within `ms` of `clock`, false when the wait ran out. */
     wait(ms: number, clock: Clock): Promise<boolean>;
 }
@@ -23,8 +27,17 @@ export declare class ActiveTurn {
     toolDenied: boolean;
     /** Claw took this turn's stop (its item's, or the interrupt): its failed end is the stop, not an error. */
     stopConfirmed: boolean;
+    /**
+     * Set once Claw took the interrupt of this turn (`/stop`): a message queued behind it need not wait for its end, which a turn
+     * stopped before Claw ran it may never report.
+     */
+    readonly stopped: Latch;
+    /** The turn went to Claw (a queued one once the turns in front of it were over or stopped): `/stop` no longer withdraws it. */
+    launched: boolean;
     /** Set once Claw runs the turn's message, or the turn is over: a message sent behind it may go then. */
     readonly running: Latch;
+    /** Set once the turn is over (or never started, or was given up while it waited): the turn behind it may go then. */
+    readonly ended: Latch;
     /** The turn is over (or never started). */
     over: boolean;
     constructor(
@@ -40,21 +53,25 @@ export interface TurnKey {
     /** For a review: "review:<item id>" or "review:<pull request>"; "" for a chat turn. */
     readonly review: string;
 }
-export type QueueRefusal = "still_working" | "one_waiting";
+export type QueueRefusal = "still_working" | "queue_full";
 export declare class TurnRegistry {
     private readonly turns;
-    /** The chat's turns, oldest first: the one Claw runs, then at most one queued behind it. */
+    /** The chat's turns, oldest first: the one Claw runs, then those queued behind it. */
     of(key: TurnKey): readonly ActiveTurn[];
     has(key: TurnKey): boolean;
     /** Registers `turn` as the first of a chat that has none; false when the chat has one. */
     claim(key: TurnKey, turn: ActiveTurn): boolean;
     /**
-     * `turn` behind the chat's running one: refused when a review is either of them, or when one already waits. Otherwise
-     * it is registered, and the caller waits for the front turn to run (`front`).
+     * `turn` behind the chat's running one: refused when a review is either of them, or when `QUEUED_TURNS_MAX` already wait (not
+     * gone to Claw yet). Otherwise it is registered last, with its place among those that wait (`waiting`: 1 is the next to go;
+     * 0 when it is the chat's first turn and runs at once).
      */
     enqueue(key: TurnKey, turn: ActiveTurn): {
         readonly front: ActiveTurn;
+        readonly waiting: number;
     } | QueueRefusal;
+    /** Every turn queued behind the chat's running one that has not gone to Claw yet is given up (`/stop`); how many there were. */
+    withdrawQueued(key: TurnKey): number;
     /** The turn is over (or never started): whatever waits behind it may go, and the chat no longer holds it. */
     drop(key: TurnKey, turn: ActiveTurn): void;
     /** A work item was stopped from its card: the review turn that follows it ends as stopped, not as a task that failed. */