@primusclaw/personal-agent 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,17 @@
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+/**
+ * The person's own settings of when they are reached (the Python `Agent._cmd_timezone`, `_cmd_quiet`, `_cmd_pause`,
+ * `_cmd_resume`): every reply in their language, and what quiet hours or a pause held is delivered as soon as nothing
+ * mutes them any more.
+ */
+export declare class SettingsCommands {
+    private readonly ctx;
+    constructor(ctx: RouterContext);
+    timezone(chat: Chat, name: string | null): Promise<void>;
+    quiet(chat: Chat, arg: string): Promise<void>;
+    pause(chat: Chat, arg: string): Promise<void>;
+    resume(chat: Chat): Promise<void>;
+    /** After a change: when nothing mutes the person any more, what was held is delivered. */
+    private releaseIfOpen;
+}

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

@@ -0,0 +1,38 @@
+import type { Part } from "../capabilities/registry.js";
+import type { ConversationRef, InboundAction, InboundEvent, OutMessage } from "../ports/surface.js";
+import type { ClickRoute, SettleOptions } from "../ports/routing.js";
+import { TaskAdmission } from "./admission.js";
+import { Chat } from "./chat.js";
+import { Credentials } from "./credentials.js";
+import type { RouterDeps } from "./deps.js";
+import { KeyOwners } from "./identity.js";
+import { TurnRegistry } from "./turn-registry.js";
+import { CommandViews } from "./views.js";
+/** What every part of the router shares: its dependencies and the services built from them, once. */
+export declare class RouterContext {
+    readonly deps: RouterDeps;
+    readonly turns: TurnRegistry;
+    readonly views: CommandViews;
+    readonly credentials: Credentials;
+    readonly admission: TaskAdmission;
+    readonly owners: KeyOwners;
+    constructor(deps: RouterDeps);
+    /** The parts of the worker that are on: what help offers and what the assistant may be asked for. */
+    parts(): ReadonlySet<Part>;
+    /** The chat an event is answered in: its conversation, as the person who sent it. */
+    chatOf(event: InboundEvent, scope: string): Chat;
+    /** A chat in another conversation of the same person (their 1:1 chat, a group a request waited in). */
+    chatIn(chat: Chat, ref: ConversationRef, scope?: string): Chat;
+    /** A click as a feature handler is given it. */
+    clickRoute(action: InboundAction, chat: Chat): ClickRoute;
+    /** THE way the router ends a click (see `settleClick`). */
+    settle(action: InboundAction, chat: Chat, card: OutMessage | string, options?: SettleOptions): Promise<boolean>;
+    /** What the turns of stopped work items must know (a review following it ends as stopped, not failed). */
+    private readonly stopListeners;
+    /** A work item was stopped from its card or a group's "停 825": the review turn following it ends as stopped. */
+    itemStopped(itemId: string): void;
+    /** The review service hears of a stopped item too (`GithubReview.item_stopped`). */
+    onItemStopped(listener: (itemId: string) => void): void;
+    /** Whether the person's 1:1 chat (or a group of theirs, `scope`) has a turn this worker follows. */
+    hasTurn(userId: string, scope?: string): boolean;
+}

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

@@ -0,0 +1,53 @@
+import type { OutMessage } from "../ports/surface.js";
+import type { Chat } from "./chat.js";
+import type { RouterDeps } from "./deps.js";
+import type { CredentialProvider } from "./features.js";
+import type { CommandViews } from "./views.js";
+/** The identity service is down for a moment while a person with no key is followed: that is not "no credential". */
+export declare class CredentialUnavailable extends Error {
+    readonly name = "CredentialUnavailable";
+}
+type CredentialDeps = Pick<RouterDeps, "store" | "exchange" | "config" | "logger">;
+/**
+ * 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`).
+ *
+ * A chat runs on the person's linked key; with TEAMS_EXCHANGE_FOR_CHAT on, on a fresh exchanged token when they have a
+ * confirmed binding, else their linked key, else they get the card that binds them.
+ */
+export declare class Credentials {
+    private readonly deps;
+    private readonly views;
+    /** What an ordinary chat calls Claw with: the exchange only when it is on for chats. */
+    private readonly chatExchange;
+    constructor(deps: CredentialDeps, views: CommandViews);
+    /** Whether chats run on exchanged tokens. */
+    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>;
+    /** 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). */
+    fresh(userId: string, fallback: string): Promise<string>;
+    /**
+     * What to read Claw with for a person when nobody is writing (a reader that follows a remote session): no question, no
+     * message; undefined when they have no credential. Throws CredentialUnavailable while the identity service is down
+     * for a person with no key.
+     */
+    background(userId: string): Promise<string | undefined>;
+    /**
+     * What a chat tells a person who cannot be answered yet; `lead` is a first sentence for a message that arrives unasked
+     * (the 1:1 message after an @mention in a group). The key's steps, or the identity binding when chats run on it.
+     */
+    unlinked(chat: Chat, lead?: string): Promise<void>;
+    /** The card that connects the person's account at the identity service (what `/github` and a review need). */
+    connectIdentity(chat: Chat, lead?: string): Promise<void>;
+    /**
+     * A one-time confirm link from the identity service, opened in a browser and confirmed once. When the service cannot
+     * be asked, the older card, whose Confirm button explains the desktop way: the person is never left with nothing.
+     */
+    bindingCard(chat: Chat, lead?: string): Promise<OutMessage>;
+    /** The `/link` steps, in the person's language (all English after a lead that has no Chinese of its own). */
+    askToLink(chat: Chat, lead?: string): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,116 @@
+import type { Integrations } from "../plugins/integrations.js";
+import type { IdentityLookup } from "../plugins/identity-lookup.js";
+import type { KeyRevoker } from "../plugins/key-revoker.js";
+import type { TokenExchange } from "../plugins/token-exchange.js";
+import type { ClawPort } from "../ports/claw/index.js";
+import type { Clock } from "../ports/clock.js";
+import type { Random } from "../ports/random.js";
+import type { RequestScope } from "../ports/request-scope.js";
+import type { Logger, LogValue } from "../ports/logger.js";
+import type { MetricsPort } from "../ports/metrics.js";
+import type { RouteHandlers } from "../ports/routing.js";
+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 { TurnRunner } from "./turn-runner.js";
+/** What a deployment sets for the router (the Python `Agent.__init__` arguments that are settings). */
+export interface RouterConfig {
+    /** The console's address, for the links the router gives (`/primus-claw/teams-link`, the memory page). */
+    readonly publicBaseUrl: string;
+    readonly botName: string;
+    /** Sessions are created with this Claw plugin ("" none). */
+    readonly pluginId: string;
+    /** Sessions are pinned to this model ("" Claw's default). */
+    readonly model: string;
+    /** What a review for a colleague runs on when its request named no model ("" the chat's model). */
+    readonly reviewModel: string;
+    /** A turn refused for want of a gateway key runs again on this model ("" never). */
+    readonly fallbackModel: string;
+    /** Ordinary chats run on exchanged tokens (TEAMS_EXCHANGE_FOR_CHAT) instead of the linked key. */
+    readonly exchangeForChat: boolean;
+    /** The parts of help that need Claw switches this worker cannot read. */
+    readonly briefEnabled: boolean;
+    readonly schedulesEnabled: boolean;
+    readonly jobWatchEnabled: boolean;
+    /** Answers on a phone get thumbs of the worker's own (TEAMS_OWN_THUMBS_MOBILE). */
+    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">;
+/** The per-person limits (Python `limits.py`): messages per window and tasks at the same time. */
+export interface RouterLimits {
+    readonly maxConcurrentTasks: number;
+    /** How long a message to the assistant may hold a task slot while its work item has not shown on the board. */
+    readonly assistantPendingSeconds: number;
+    /** Counts a message of `userId`; when refused, whether the person is told this time and when they may write again. */
+    checkMessage(userId: string): {
+        readonly allowed: true;
+    } | RateRefusal;
+    /** What a refused message says, in `lang`. */
+    rateNotice(lang: "en" | "zh", retryAfterSeconds: number): string;
+    /** What a refused task says, in `lang`: `running` tasks, `what` the one refused ("" none named). */
+    concurrencyNotice(lang: "en" | "zh", running: number, what: string): string;
+}
+export interface RateRefusal {
+    readonly allowed: false;
+    readonly notify: boolean;
+    readonly retryAfterSeconds: number;
+    readonly limit: number;
+    readonly windowSeconds: number;
+}
+/** Stored conversation references, as the channel reads and writes them. */
+export interface ChannelRefs {
+    /** The reference a stored one is (Teams: the Bot Framework reference the Python worker stored); undefined: not one. */
+    refOf(stored: JsonObject): ConversationRef | undefined;
+}
+/** Notices held by quiet hours or a pause (Python `proactive.Proactive`). */
+export interface ProactiveHold {
+    /** Why the person is muted now ("quiet" or "paused"); null when nothing mutes them. */
+    muted(userId: string): string | null;
+    /** Deliver what was held for the person. */
+    release(userId: string): Promise<void>;
+}
+/** Everything the router is built with. A feature that is off is given as undefined (GitHub, notifications). */
+export interface RouterDeps {
+    readonly config: RouterConfig;
+    readonly surface: Surface;
+    readonly channel: ChannelRefs;
+    readonly store: RouterStore;
+    readonly claw: ClawPort;
+    readonly clock: Clock;
+    /** Where the event being handled is kept for what it starts (none: `noRequestScope`). */
+    readonly requestScope?: RequestScope;
+    readonly random: Random;
+    readonly logger: Logger;
+    readonly metrics: MetricsPort;
+    readonly securityEvent: (name: SecurityEventName, fields: Readonly<Record<string, LogValue>>) => void;
+    readonly identity: IdentityLookup;
+    readonly keyRevoker: KeyRevoker;
+    readonly exchange: TokenExchange;
+    readonly limits: RouterLimits;
+    readonly assistant: AssistantChat;
+    readonly remote: RemoteChat;
+    readonly turns: TurnRunner;
+    /** The Stop cards of turns a phone starts. */
+    readonly stopCards: StopCards;
+    readonly proactive: ProactiveHold;
+    readonly observing: Observing;
+    readonly github: GithubChat | undefined;
+    /** The review-stop words of a group (with the review service on). */
+    readonly reviewStop: ReviewStopReader | undefined;
+    /** What a chat can hand back to this worker (the review service's `review_for_other`; empty without it). */
+    readonly handoffs: readonly string[];
+    readonly channelContext: ChannelContextBuilder;
+    readonly messageText: MessageText;
+    /** `/whoami`'s connection lines (the review service's renderer, which also says them without it). */
+    readonly connectionsText: ConnectionsText;
+    /** The "Report a problem" card under a message that says something went wrong (feedback's view); undefined: none. */
+    readonly reportView: (userId: string, scope: string) => OutMessage | undefined;
+    /** The note card a settled click ends as. */
+    readonly note: NoteFactory;
+    readonly subscriptions: Subscriptions | undefined;
+    readonly handlers: RouteHandlers;
+    readonly integrations: Integrations;
+}

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

@@ -0,0 +1,256 @@
+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 { 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
+ * assistant, remote agents, the turn engine, the review service, observing, notifications) and given to the router by
+ * the assembly; the router never reaches into a feature, and a feature that is off is given as its `off` value.
+ */
+/** A fresh credential per call for a chat that runs on exchanged tokens (they expire); undefined: the key as it is. */
+export type CredentialProvider = (() => Promise<string>) | undefined;
+/** A 1:1 message on the plain route (the Python `Assistant.route`). */
+export interface AssistantRouteRequest {
+    readonly userId: string;
+    readonly credential: string;
+    readonly prompt: string;
+    readonly conversation: Conversation;
+    readonly files: readonly InboundFile[];
+    /** Present only where remote agents are on: what this chat is attached to (null for nothing). */
+    readonly attached?: JsonObject | null;
+    /** Told (session, message id or null when Claw queued it) once Claw has taken the message (a phone's Stop card). */
+    readonly onSent?: OnSent;
+}
+/** Claw took a message to the assistant: its session and the message id its turn answers (null: queued). */
+export type OnSent = (sessionId: string, messageId: string | null) => void;
+/** A message of a person the assistant understands (the Python `Assistant.understand`). */
+export interface UnderstandRequest {
+    readonly userId: string;
+    /** The exchanged identity token when there is one, else the linked key. */
+    readonly credential: string;
+    /** The linked key beside an identity token, for the model ("" when `credential` is the key). */
+    readonly modelKey: string;
+    readonly prompt: string;
+    /** The chat's context (`channel_context`). */
+    readonly context: JsonObject;
+    readonly lang: Lang;
+    readonly conversation: Conversation;
+    readonly files: readonly InboundFile[];
+    readonly onSent?: OnSent;
+}
+/** The person's assistant (Python `assistant.Assistant`). */
+export interface AssistantChat {
+    /** A 1:1 chat that talks to the assistant (no sessions of its own). */
+    on(userId: string): boolean;
+    /** The assistant reads every message of this person (only an exact command is read by the router). */
+    understands(userId: string): boolean;
+    /** The assistant can be sent a message now. */
+    reachable(userId: string): boolean;
+    /** The reply, in `lang`, to a command that has no meaning with the assistant on; undefined when `text` is not one. */
+    hiddenCommand(text: string, lang: Lang): string | undefined;
+    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.
+     */
+    stop(userId: string, credential: string, conversation: Conversation, onlyMessage?: string): Promise<boolean>;
+    /** Forget what is kept for the person (they unlinked). */
+    forget(userId: string): void;
+    /** True when the assistant took the message. */
+    route(request: AssistantRouteRequest): Promise<boolean>;
+    /** True when it was sent. */
+    understand(request: UnderstandRequest): Promise<boolean>;
+    /** What a message of files and no words asks, in `lang`. */
+    filesOnly(lang: Lang): string;
+}
+/** What a chat is attached to, as help's first lines say it (each already made safe to show). */
+export interface Attachment {
+    readonly label: string;
+    readonly host: string;
+    /** "" when the session has no folder. */
+    readonly cwd: string;
+    /** The line that says where the chat box goes while the session card is the window, in the language asked for. */
+    readonly cardWindowLine: string;
+}
+/** One turn of an attached agent, as the remote-agent feature follows it: the work that reads it (null: none yet). */
+export interface RemoteTurn {
+    readonly task: {
+        readonly done: Promise<void>;
+        readonly running: boolean;
+    } | null;
+}
+export interface RemotePrompt {
+    readonly message: InboundMessage;
+    /** The chat's own identity (a group binding's chat key, or the person in their 1:1 chat). */
+    readonly chat: UserRef;
+    readonly credential: string;
+    readonly prompt: string;
+    readonly conversation: Conversation;
+    readonly provider: CredentialProvider;
+}
+export interface RemoteAgentCommand {
+    readonly chat: UserRef;
+    readonly credential: string;
+    /** What follows `/agent`. */
+    readonly args: string;
+    readonly conversation: Conversation;
+    /** Undefined for a command the assistant asked for. */
+    readonly message: InboundMessage | undefined;
+    readonly provider: CredentialProvider;
+}
+/** Agents on the person's own machines (Python `remote.RemoteAgents`). Keys are chat keys: a person, or a group binding. */
+export interface RemoteChat {
+    readonly enabled: boolean;
+    attached(chatKey: string): boolean;
+    /** The chat is the agent's window itself (direct chat). */
+    direct(chatKey: string): boolean;
+    windowMode(chatKey: string): "card" | "chat";
+    /** The message replies quoting the session's card. */
+    quotesWindow(chatKey: string, message: InboundMessage): boolean;
+    /** A turn of the attached agent is running for this person. */
+    running(userId: string): boolean;
+    /** What the chat is attached to, as the assistant is told it (null: nothing). */
+    chatContext(userId: string, credential: string): Promise<JsonObject | null>;
+    attachment(chatKey: string, lang: Lang): Attachment | undefined;
+    prompt(request: RemotePrompt): Promise<void>;
+    /**
+     * True when the attached agent was the one to stop. `only`: stop only while that turn (`currentTurn`) still runs; false,
+     * with nothing said or stopped, when it does not.
+     */
+    stop(chat: UserRef, credential: string, conversation: Conversation, only?: RemoteTurn): Promise<boolean>;
+    /**
+     * The attached agent's turn running for this chat now (undefined: none), compared by identity. Absent on a remote-agent
+     * feature that does not follow turns: a phone's message to an agent then gets no Stop card.
+     */
+    currentTurn?(chatKey: string): RemoteTurn | undefined;
+    /** The chat's session card is the window (it has a Stop of its own). */
+    windowed?(chatKey: string): boolean;
+    agents(sender: UserRef, credential: string, conversation: Conversation): Promise<void>;
+    agent(command: RemoteAgentCommand): Promise<void>;
+    forgetPerson(userId: string): void;
+    /** The chat key of a person's binding in a group chat. */
+    groupChatKey(userId: string, scope: string): string;
+}
+/** The person's notification subscription in Claw (Python `subscriptions.Subscriptions`); undefined when notifications are off. */
+export interface Subscriptions {
+    ensure(userId: string): Promise<void>;
+    /** Before the key is revoked: Claw needs it to delete the subscription. */
+    remove(userId: string, key: string): Promise<void>;
+}
+/** Observing a group for a person's assistant (Python `observe.Observer`). */
+export interface Observing {
+    /** A group message not addressed to the bot: to the group's observer, if it has one. */
+    forward(message: InboundMessage): Promise<void>;
+    mayTurnOn(userId: string): boolean;
+    /** The suggestions the observed groups make for the person (`/board`). */
+    board(userId: string, credential: string, conversation: Conversation): Promise<void>;
+}
+/** 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. */
+    remember(message: InboundMessage): void;
+    /** Help's values of the person's GitHub ("github", "delegation", "confirm_mode"); those it cannot read are left out. */
+    helpValues(userId: string, lang: Lang): Promise<Readonly<Record<string, string>>>;
+    /**
+     * Beside a question about the person's own GitHub while Claw has no token of theirs: the connect card, sent before the
+     * question goes on; `again` asks it again once they connect.
+     */
+    offerConnect(request: {
+        readonly sender: UserRef;
+        readonly credential: string;
+        readonly text: string;
+        readonly lang: Lang;
+        readonly conversation: Conversation;
+        readonly again: () => Promise<void>;
+    }): Promise<void>;
+    /** The open confirmations of the person (the assistant's context). */
+    pendingConfirmations(userId: string): readonly JsonObject[];
+    /**
+     * The person's GitHub binding at the identity service, as `/whoami` passes it on to `ConnectionsText` (the review
+     * service's own value: bound, none, or not known just now).
+     */
+    connectionState(userId: string): Promise<unknown>;
+}
+/** What `/whoami` lists after its first line (the Python `github_connect.connections_text`, the review service's). */
+export interface WhoamiConnections {
+    readonly owner: KeyOwner | undefined;
+    /** `GithubChat.connectionState`; undefined without the review service. */
+    readonly githubState: unknown;
+    /** Claw's answer about the person's GitHub tools (undefined: none, or could not be asked). */
+    readonly connection: GithubConnection | null | undefined;
+    /** Whether Claw could say. */
+    readonly connectionKnown: boolean;
+    readonly githubPart: boolean;
+    /** [enabled, available] of the person's memory in Claw; undefined: not known just now. */
+    readonly memory: readonly [boolean, boolean] | undefined;
+    readonly memoryPage: string;
+    readonly zh: boolean;
+}
+export type ConnectionsText = (connections: WhoamiConnections) => string;
+/** The person's own review-stop words in a group ("停 825"): the pull requests named, as [owner/repo or "", number]. */
+export type ReviewStopReader = (text: string) => readonly (readonly [string, number])[];
+/** What a message to the assistant carries about the chat (the Python `understanding.channel_context`). */
+export interface ChannelContextRequest {
+    readonly channelMessageId: string;
+    readonly userId: string;
+    readonly message: InboundMessage;
+    /** The parts of the worker that are on (help's parts): which actions the chat declares. */
+    readonly parts: ReadonlySet<string>;
+    /** What this chat can be handed back to carry out itself (the review service's `review_for_other`). */
+    readonly handoffs: readonly string[];
+    /** Present only where remote agents are on: what the chat is attached to (null: nothing). */
+    readonly attached?: JsonObject | null;
+    /** "on_behalf" for a message this worker posted for the person. */
+    readonly via: string;
+}
+export interface ChannelContext {
+    readonly context: JsonObject;
+    /** The names of the actions it declared. */
+    readonly actions: readonly string[];
+    /** The Claw user ids of the people it names. */
+    readonly people: readonly string[];
+}
+export type ChannelContextBuilder = (request: ChannelContextRequest) => ChannelContext;
+/** Reading what a message carries besides its words (the channel's inbound text, W3: the Python `activity` helpers). */
+export interface MessageText {
+    /** The message(s) it quotes, as text for the model ("" none). `group`: as a group chat shows them. */
+    quoteBlock(message: InboundMessage, group: boolean): string;
+    /** `text` with the address behind each of the message's links. */
+    withLinks(text: string, message: InboundMessage): string;
+    /** `text` after the quote block it answers. */
+    withQuote(text: string, quote: string): string;
+    /** The line that names the files the channel gave no way to fetch (undefined: none). */
+    unreadable(message: InboundMessage): {
+        readonly line: string;
+        readonly count: number;
+    } | undefined;
+}
+/** A button on a note card: what it says and what pressing it sends back (the card data's verb and fields). */
+export interface NoteButton {
+    readonly title: string;
+    readonly verb: string;
+    readonly data: Readonly<Record<string, string>>;
+    readonly style?: "positive" | "destructive";
+}
+/** The note card a settled click ends as (rendered by the channel; the Python `render.note_card`). */
+export type NoteFactory = (text: string, options?: {
+    readonly title?: string;
+    readonly tone?: string;
+    readonly buttons?: readonly NoteButton[];
+}) => OutMessage;
+/** Which kind of turn a phone's Stop card stops. */
+export type StopCardKind = "session" | "assistant" | "remote";
+/** One Stop card's offer (the turn engine's `StopButtons`): whose, which kind, the card, and whether it was used. */
+export interface StopCardOffer {
+    readonly kind: StopCardKind;
+    readonly alive: (credential: string) => Promise<boolean>;
+    cardId: string | undefined;
+    used: boolean;
+}
+/** The Stop cards of turns started from a phone, whose own Stop is greyed out (the turn engine's `StopButtons`). */
+export interface StopCards {
+    offer(userId: string, kind: StopCardKind, conversation: Pick<Conversation, "post" | "delete">, lang: string, alive: (credential: string) => Promise<boolean>, ended: Promise<unknown>): StopCardOffer;
+    /** The offer of a card this person pressed; undefined for an unknown, forgotten or someone else's token. */
+    get(token: string, userId: string): StopCardOffer | undefined;
+}

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

@@ -0,0 +1,26 @@
+import type { InboundMessage } from "../ports/surface.js";
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+import type { PersonalText } from "./personal-text.js";
+export interface GroupWords {
+    readonly text: string;
+    readonly quote: string;
+    readonly sent: string;
+}
+/**
+ * A group chat bound to one of the sender's agent sessions (one group, one session at a time; the Python
+ * `Agent._group_remote`). "切到 X 上的 claude" (`/agent attach REF`) binds the group for the sender, "回到助理"
+ * (`/agent detach`) unbinds it; while bound, the sender's @-messages go to that session and "停掉它" stops its turn. The
+ * binding is the sender's own: another member's message is never read by it. False: not a message about the binding.
+ */
+export declare class GroupRemote {
+    private readonly ctx;
+    private readonly text;
+    constructor(ctx: RouterContext, text: PersonalText);
+    private chatOf;
+    /** The `/agent` arguments a group message asks for: typed, said as a switch, or "回到助理" while bound. */
+    private agentArgs;
+    route(message: InboundMessage, chat: Chat, key: string, words: GroupWords): Promise<boolean>;
+    /** A message of a sender whose binding holds this group. */
+    private toBound;
+}

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

@@ -0,0 +1,42 @@
+import type { MessageInterceptor } from "../ports/routing.js";
+import type { InboundAction, InboundMessage } from "../ports/surface.js";
+import { type Chat } from "./chat.js";
+import type { SessionCommands } from "./commands-session.js";
+import type { RouterContext } from "./context.js";
+import type { GroupRemote } from "./group-remote.js";
+import type { Onboarding } from "./onboarding.js";
+import { type PersonalText } from "./personal-text.js";
+import type { TurnStarter } from "./turn-start.js";
+/**
+ * A group chat (the Python `Agent._route_group`). The bot acts on a message only when it is @mentioned, and everything
+ * runs as the SENDER: their own key, their own session for this conversation. No other member's credential is read.
+ */
+export declare class GroupRouter {
+    private readonly ctx;
+    private readonly text;
+    private readonly sessions;
+    private readonly onboarding;
+    private readonly remote;
+    private readonly starter;
+    constructor(ctx: RouterContext, text: PersonalText, sessions: SessionCommands, onboarding: Onboarding, remote: GroupRemote, starter: TurnStarter);
+    route(event: InboundMessage | InboundAction, chat: Chat): Promise<void>;
+    /** A button in a group: only those of the presser's own cards that may be pressed there answer. */
+    private click;
+    private words;
+    private message;
+    /** Help, and the commands a group does not take (they are a 1:1 chat's). True when the message was answered. */
+    private groupOwn;
+    /** A command of a 1:1 chat (`/agent attach|detach` binds the group: it stays the group's). */
+    private oneToOneOnly;
+    private withKey;
+    /** Which account, in a group: never the sender's email. */
+    private whoami;
+    /**
+     * "停 825", from a person the assistant understands: their reviews of those pull requests are stopped in Claw at once
+     * (not said to the assistant, where it could wait while the merge happens). Placed by the assembly among the group's
+     * interceptors (after feedback, before review requests).
+     */
+    reviewStopInterceptor(): MessageInterceptor;
+    private stopReviews;
+    private stopReview;
+}

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

@@ -0,0 +1,18 @@
+import type { IdentityLookup, KeyOwner } from "../plugins/identity-lookup.js";
+/**
+ * What the router asks of the platform that issued a key (the Python `safe.whoami`, `safe.safe_user`, `safe.user_id_of`):
+ * one owner lookup, read three ways. A lookup that fails says nothing. Values are stripped as Python strips them (`pyStrip`:
+ * a byte-order mark, which JavaScript's trim() takes for whitespace, stays).
+ */
+export declare class KeyOwners {
+    private readonly identity;
+    constructor(identity: IdentityLookup);
+    /** The owner when the platform named them ("" names are no owner, as `safe_user` reads it). */
+    owner(key: string): Promise<KeyOwner | undefined>;
+    /** [name, email] of the key's owner (`safe.whoami`). */
+    whoami(key: string): Promise<readonly [string, string] | undefined>;
+    /** The platform's id of the key's owner (`safe.user_id_of`). */
+    userIdOf(key: string): Promise<string | undefined>;
+    /** " to SaFE user NAME (EMAIL)" for the key, or undefined when the platform cannot say (`Agent._who_line`). */
+    whoLine(key: string | undefined, withEmail?: boolean): Promise<string | undefined>;
+}

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

@@ -0,0 +1,26 @@
+/** The router's public API: what the channel renders, what features implement, what the assembly builds. */
+export * from "./chat.js";
+export * from "./credentials.js";
+export * from "./deps.js";
+export * from "./features.js";
+export * from "./identity.js";
+export * from "./turn-registry.js";
+export type { ReviewRunFields, TurnHooks, TurnOutcome, TurnRunner } from "./turn-runner.js";
+export * from "./views.js";
+export * from "../capabilities/help.js";
+export * from "../capabilities/natural.js";
+export * from "../capabilities/registry.js";
+export * from "../capabilities/visibility.js";
+export * from "../commands/agent-args.js";
+export * from "../commands/names.js";
+export * from "../commands/parse.js";
+export * from "../commands/repo.js";
+export * from "../locales/commands.js";
+export * from "../locales/transparency.js";
+export * from "./admission.js";
+export * from "./command-table.js";
+export * from "./context.js";
+export * from "./onboarding.js";
+export * from "./router.js";
+export * from "./turn-start.js";
+export * from "./time.js";

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

@@ -0,0 +1,26 @@
+import type { PendingRequest } from "../ports/store/onboarding.js";
+import type { InboundAction } from "../ports/surface.js";
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+/** Runs a group request that waited for its asker to connect (`GroupRouter.resumeRequest`). */
+export type ResumeRequest = (chat: Chat, pending: PendingRequest, announce: boolean) => Promise<boolean>;
+/**
+ * Connecting and disconnecting a chat (the Python `Agent._cmd_link`, `_cmd_unlink`, `_confirm_binding`). The `/link`
+ * code is the proof that the same human holds the console session that minted it and this channel account; every
+ * attempt goes through the store, which counts it against the limits and records it.
+ */
+export declare class LinkCommands {
+    private readonly ctx;
+    private readonly resume;
+    constructor(ctx: RouterContext, resume: ResumeRequest);
+    link(chat: Chat, code: string | null, messageId: string): Promise<void>;
+    private linked;
+    unlink(chat: Chat): Promise<void>;
+    /** A chat that runs on the exchange stays connected through the person's binding, which only they can remove. */
+    private stillBound;
+    /**
+     * The person pressed the button that says they confirmed: the binding is looked for now. The worker cannot make it,
+     * only the person can; not there yet, the card comes back with the link that is still open (or a new one).
+     */
+    confirmBinding(action: InboundAction, chat: Chat): Promise<void>;
+}

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

@@ -0,0 +1,5 @@
+/** One lock per key: what runs under it runs one at a time, in the order it asked (the Python `asyncio.Lock` per user). */
+export declare class KeyedLock {
+    private readonly tails;
+    run<T>(key: string, work: () => Promise<T>): Promise<T>;
+}