@primusclaw/personal-agent 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,51 @@
+import type { PendingRequest } from "../ports/store/onboarding.js";
+import type { InboundAction, InboundMessage } from "../ports/surface.js";
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+import type { TurnStarter } from "./turn-start.js";
+/** Opening a 1:1 chat and sending the steps may hold the card back this long, at most. */
+export declare const ONBOARDING_DM_BUDGET_SECONDS = 15;
+/** What a member asked in a group, kept for when they connect (`quote` and `sent` as the turn takes them). */
+export interface GroupAsk {
+    readonly text: string;
+    readonly quote: string;
+    readonly sent: string;
+    /** Kept to run later (not for /new, /stop, /whoami, which mean nothing to replay). */
+    readonly keep: boolean;
+    /** What they lack is the identity binding (a review for a colleague needs it), not what a chat runs on. */
+    readonly identity: boolean;
+}
+/**
+ * A group member who has not connected an account (the Python `Agent._onboard_group_member`, `_send_onboarding_dm`,
+ * `_onboard_click`, `_resume_group_request`, `_targeted_in_group`): a card addressed to them (one per person per chat
+ * per day) and, once a day, a 1:1 message with the steps; what they asked runs in the group as soon as they connect
+ * (within the store's 15 minutes). Nothing here uses any credential, and the card carries no part of the request.
+ */
+export declare class Onboarding {
+    private readonly ctx;
+    private readonly starter;
+    constructor(ctx: RouterContext, starter: TurnStarter);
+    /** The person's 1:1 chat, opened within the budget; undefined when the channel cannot or does not in time. */
+    private openPersonal;
+    member(message: InboundMessage, chat: Chat, ask: GroupAsk): Promise<void>;
+    /**
+     * The steps in a 1:1 chat with the member: true when they have them (sent now, or with `claim` earlier today). False
+     * when it did not work; the in-group card is then the only help, and the day's message is not used up.
+     */
+    sendSteps(chat: Chat, claim: boolean, identity?: boolean): Promise<boolean>;
+    /**
+     * Connect under an onboarding card. The store says whose card it is (never the card); anyone else gets their own card
+     * back with a line saying so. The person it is for gets the steps in a 1:1 chat, or in the card when that cannot be done.
+     */
+    click(action: InboundAction, chat: Chat): Promise<void>;
+    /**
+     * The member connected while their group request waited: it runs there, as them, and the group is told so. `notify`
+     * (the chat where they connected) hears if this could not be done; a failure never undoes the connection.
+     */
+    resume(notify: Chat, pending: PendingRequest, announce: boolean): Promise<boolean>;
+    /**
+     * A private message in a group (picked under "/"): an answer in the group would show everyone what only the bot was
+     * meant to see, so the sender gets one line in their 1:1 chat saying where to ask instead.
+     */
+    targeted(chat: Chat): Promise<void>;
+}

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

@@ -0,0 +1,34 @@
+import type { JsonObject } from "../json.js";
+import type { InboundAction, InboundMessage } from "../ports/surface.js";
+import { type Chat } from "./chat.js";
+import type { CommandSets } from "./command-table.js";
+import type { RouterContext } from "./context.js";
+import type { PersonalText } from "./personal-text.js";
+/**
+ * A 1:1 chat (the Python `Agent._dispatch` from the personal-chat check on): what needs no account first (`/link`, the
+ * language, a review request, feedback, a click that answers as the person's identity), then the person's credential, then
+ * their commands, their buttons, and the message on its way.
+ */
+export declare class PersonalRouter {
+    private readonly ctx;
+    private readonly sets;
+    private readonly text;
+    private readonly stopPress;
+    private readonly showHere;
+    constructor(ctx: RouterContext, sets: CommandSets, text: PersonalText);
+    route(event: InboundMessage | InboundAction, chat: Chat): Promise<void>;
+    /** Linked before the Claw user id was kept: it is read now. */
+    private backfill;
+    private message;
+    /** What a 1:1 message can do with no account: true when it was taken. */
+    private beforeCredential;
+    private handlerOf;
+    private click;
+    private ownClick;
+}
+/** What is stored for proactive messages: the channel's own reference, as it gave it. */
+export declare function wireOf(event: {
+    readonly conversation: {
+        readonly wire: Readonly<Record<string, unknown>>;
+    };
+}): JsonObject;

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

@@ -0,0 +1,62 @@
+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";
+/**
+ * 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`):
+ * to the remote agent the chat is attached to, to the person's assistant, or to Claw as a turn.
+ */
+export declare class PersonalText {
+    private readonly ctx;
+    private readonly commands;
+    private readonly starter;
+    constructor(ctx: RouterContext, commands: CommandTable, starter: TurnStarter);
+    /**
+     * What the person wrote, with a word of the commands menu read as its command and a sentence help teaches read as the
+     * command it means; a sentence for what this chat cannot do right now stays words.
+     */
+    textOf(message: InboundMessage, group?: boolean): string;
+    onText(message: InboundMessage, chat: Chat, key: string): Promise<void>;
+    /**
+     * Whether this 1:1 message goes to the remote session the chat is attached to: only words the person typed, and not
+     * those that start by naming the bot. A chat whose session card is the window keeps its chat box for the bot: only a
+     * reply that quotes the card goes to the session.
+     */
+    talksToAgent(message: InboundMessage): boolean;
+    /** The files that go to Claw with a message; the person is told about the ones that do not, and they are counted. */
+    attachments(message: InboundMessage, chat: Chat, elsewhere?: boolean): Promise<readonly InboundFile[]>;
+    /** What the chat is attached to, for the assistant (only where remote agents are on). */
+    private attached;
+    /** A 1:1 message that is no command, as it goes on to the attached agent, the assistant or Claw. */
+    sentOn(message: InboundMessage, chat: Chat, key: string): Promise<void>;
+    /**
+     * A message to an attached chat that is about the sessions themselves (switch, open a new one), with the assistant on to
+     * read it: the words alone (a quote or a file goes to the agent with them).
+     */
+    private sessionControl;
+    /** A message the assistant takes when it is on, else a turn of Claw's. */
+    private toAssistantOrTurn;
+    /** A prompt for the attached agent, within the task limit (the slot is held until the remote turn counts as running). */
+    private remotePrompt;
+    /**
+     * Beside a question about the person's own GitHub while Claw has no token of theirs: the connect card first; once they
+     * connect, the question is asked again as a message of its own (an id of its own), with a credential read again then.
+     */
+    offerGithub(message: InboundMessage, chat: Chat, key: string, text: string, goOn: (message: InboundMessage, credential: string) => Promise<void>): Promise<void>;
+    understand(message: InboundMessage, chat: Chat, key: string): Promise<void>;
+    /**
+     * A message of a person the assistant understands: to their assistant, as they wrote it (with what it quotes and the
+     * addresses behind its links), with the chat's context, and as the person (their exchanged identity token, their key
+     * beside it for the model; with no token, on their key). Files go with it; files alone are a message too.
+     */
+    understood(message: InboundMessage, chat: Chat, key: string): Promise<void>;
+}
+/** The message came with files, whether the channel gave a way to fetch them or not (Python `any(inbound_files(activity))`). */
+export declare function hasFiles(message: InboundMessage): boolean;
+/**
+ * A review request does not take the files sent with it, and the person is told so (a review reads the pull request):
+ * what the review service calls after it took such a message.
+ */
+export declare function filesNotReviewed(ctx: RouterContext, chat: Chat, message: InboundMessage, text: string): Promise<void>;

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

@@ -0,0 +1,57 @@
+import type { InboundEvent, InboundMessage, UserRef } from "../ports/surface.js";
+import type { ReviewSlots } from "./admission.js";
+import { Chat } from "./chat.js";
+import { CommandTable } from "./command-table.js";
+import { RouterContext } from "./context.js";
+import type { RouterDeps } from "./deps.js";
+import { GroupRouter } from "./group-router.js";
+import { Onboarding } from "./onboarding.js";
+import { TurnStarter, type RunningTurn, type StartTurn } from "./turn-start.js";
+/**
+ * The entry point of every inbound event (the Python `Agent.handle`, `_route`, `_settle_click`, `_dispatch`): idempotent
+ * per event id; a message over its sender's rate is dropped before anything is read for it; a group message not addressed
+ * to the bot goes to the group's observer; a group, a 1:1 chat, anything else is told where the bot works. Whatever a click
+ * handler left open is settled here, so a click never stays a "Working on it..." card.
+ */
+export declare class Router {
+    readonly ctx: RouterContext;
+    readonly starter: TurnStarter;
+    readonly onboarding: Onboarding;
+    readonly commands: CommandTable;
+    private readonly text;
+    private readonly personal;
+    readonly group: GroupRouter;
+    constructor(deps: RouterDeps);
+    handle(event: InboundEvent): Promise<void>;
+    private route;
+    /** The safety net under every card click: a click whose card is still the placeholder ends with a note. */
+    private settleOpen;
+    private vote;
+    private dispatch;
+    /** The message is /stop (typed, the menu word, or a sentence that means it): what a refused person can still send. */
+    private static isStop;
+    /**
+     * Counts a message against its sender's rate, across all their chats. False: over it, dropped, and the person is told
+     * once per burst. /stop is never counted or refused; a group message that does not mention the bot is not counted.
+     */
+    private withinRate;
+    /** Start (or queue) a turn: the review service starts its reviews here. */
+    startTurn(request: StartTurn): Promise<RunningTurn | undefined>;
+    /** Admit up to `count` pull requests of one review request against the person's task limit. */
+    admitReviews(chat: Chat, activityId: string, count: number, boardKey: string): Promise<ReviewSlots>;
+    /** A command the assistant asked the chat to carry out, as if typed (no message: those that need one are refused). */
+    runCommand(text: string, chat: Chat): Promise<boolean>;
+    /** The person's 1:1 chat has a turn of the old kind running (the assistant lets it finish). */
+    hasPersonalTurn(userId: string): boolean;
+    /**
+     * A work item was stopped from its card (the assistant's Stop): the review turn this router follows for it ends as
+     * stopped, not as a task that failed, as when a group's "停 N" stops it (Python `Agent._item_stopped`).
+     */
+    itemStopped(itemId: string): void;
+    /** A chat as the router answers in it, for work that runs on its own (no client locale). */
+    chat(sender: UserRef, conversation: Chat["conversation"], scope?: string): Chat;
+    /** What the review service says when the files of a review request do not go with it. */
+    filesNotReviewed(chat: Chat, message: InboundMessage, text: string): Promise<void>;
+    /** The turns that run now, for a test to wait on. */
+    settled(): Promise<void>;
+}

package/dist/types/routing/show-here.d.ts

@@ -0,0 +1,18 @@
+import type { InboundAction } from "../ports/surface.js";
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+/**
+ * A press on "Show here" (1:1 chat only; Python agent.py `_show`): that session's last answer is posted in the chat and the
+ * session becomes the chat's current one. The card is not trusted: the session is read with the PRESSER's own credential,
+ * and Claw refuses a session that is not theirs, so nothing is posted and nothing is switched then. The card is replaced on
+ * every outcome; where pressing again can help it comes back with its button.
+ */
+export declare class ShowHere {
+    private readonly ctx;
+    constructor(ctx: RouterContext);
+    click(action: InboundAction, chat: Chat, key: string): Promise<void>;
+    /** The session's last answer (undefined: none finished); null when it could not be read (the card was replaced). */
+    private read;
+    /** The chat has this session again, and no repository waits for a new one. */
+    private switchTo;
+}

package/dist/types/routing/stop-press.d.ts

@@ -0,0 +1,19 @@
+import type { InboundAction } from "../ports/surface.js";
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+/**
+ * A press on a Stop card sent before the worker stopped sending them (the Python `Agent._turn_stop_click`, `_drop_tapped`,
+ * after internal #481: a turn from a phone is stopped by saying 停止 or /stop, and no card is offered any more). Such a card
+ * names no turn this worker runs, so the press stops nothing and says so; the pressed card is deleted, never edited (a phone
+ * does not redraw an edit), and where it cannot be deleted it is closed to a line.
+ */
+export declare class StopPress {
+    private readonly ctx;
+    constructor(ctx: RouterContext);
+    press(action: InboundAction, chat: Chat): Promise<void>;
+    /**
+     * Take a pressed card away: deleted (settled, so the safety net leaves it alone); where the channel refuses the delete,
+     * closed to `line`, except in a chat that is an agent's window, where nothing is edited and the card is left as it is.
+     */
+    private dropTapped;
+}

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

@@ -0,0 +1,31 @@
+/** A moment as a wall clock in a time zone shows it. */
+export interface Wall {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    /** "Mon", "Tue", ... (Python's `%a` in the C locale). */
+    readonly weekday: string;
+}
+/**
+ * Whether `name` is a time zone the worker takes (Python `ZoneInfo(name)` on the tz database's file names): a name the
+ * runtime knows, written as the database writes it ("Asia/Shanghai", "UTC", "Etc/GMT+8"; not "asia/shanghai" or "+08:00").
+ */
+export declare function isTimeZone(name: string): boolean;
+/** The person's zone (`proactive.zone_of`): theirs when it is one, else the default. */
+export declare function zoneOf(timezone: string): string;
+/** `epochSeconds` on the wall clock of `zone`. */
+export declare function wallClock(epochSeconds: number, zone: string): Wall;
+export declare function two(value: number): string;
+/** "HH:MM" of a wall clock. */
+export declare function hhmm(wall: Wall): string;
+/** Python's `%b`. */
+export declare function monthName(wall: Wall): string;
+/** Days from `then` to `now` on the calendar (both wall dates in one zone). */
+export declare function daysBetween(then: Wall, now: Wall): number;
+/**
+ * When a session was last used, in the person's zone: "today 12:40", "yesterday 18:05", else "03 Oct 09:15" (in Chinese
+ * "今天 12:40", "昨天 18:05", else "10月03日 09:15") (the Python `render.when_text`).
+ */
+export declare function whenText(at: number, now: number, zone: string, lang: string): string;

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

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+import type { Clock } from "../ports/clock.js";
+/** 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;
+    /** True when it was set within `ms` of `clock`, false when the wait ran out. */
+    wait(ms: number, clock: Clock): Promise<boolean>;
+}
+export declare class ActiveTurn {
+    /** A review for a colleague: its own session, so nothing is queued behind it. */
+    readonly review: boolean;
+    /** A review that is a work item of Claw's: a Stop on its card is this turn's stop as well. */
+    readonly itemId: string;
+    stopRequested: boolean;
+    /** The person pressed Deny on one of this turn's approval cards. */
+    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 runs the turn's message, or the turn is over: a message sent behind it may go then. */
+    readonly running: Latch;
+    /** The turn is over (or never started). */
+    over: boolean;
+    constructor(
+    /** A review for a colleague: its own session, so nothing is queued behind it. */
+    review?: boolean, 
+    /** A review that is a work item of Claw's: a Stop on its card is this turn's stop as well. */
+    itemId?: string);
+}
+/** What a turn is kept under: a person and a chat ("" the 1:1 chat), and for a review the item or the pull request. */
+export interface TurnKey {
+    readonly userId: string;
+    readonly scope: string;
+    /** 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 declare class TurnRegistry {
+    private readonly turns;
+    /** The chat's turns, oldest first: the one Claw runs, then at most one 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`).
+     */
+    enqueue(key: TurnKey, turn: ActiveTurn): {
+        readonly front: ActiveTurn;
+    } | QueueRefusal;
+    /** 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. */
+    itemStopped(itemId: string): void;
+    /** The person's turns, one per chat and one per review (what counts against their task limit). */
+    countFor(userId: string): number;
+    /** The review work items the person's turns follow (the board must not count them a second time). */
+    reviewItemsOf(userId: string): Set<string>;
+    get size(): number;
+}
+/** The key of a person's chat turn. */
+export declare function chatTurnKey(userId: string, scope?: string): TurnKey;
+/** The key of a review turn: its item when Claw made one (one open review per pull request), else the pull request. */
+export declare function reviewTurnKey(userId: string, scope: string, itemId: string, pull: string): TurnKey;

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

@@ -0,0 +1,82 @@
+import type { Lang } from "../locales/lang.js";
+import type { Conversation, InboundFile, OutMessage } from "../ports/surface.js";
+import type { CredentialProvider } from "./features.js";
+/**
+ * The turn engine as the router starts it (the Python `turn.TurnContext` and `run_turn`). The router decides whether a
+ * turn may start (the person's task limit, the chat's queue) and in which session; the engine sends the message to
+ * Claw, follows the session's stream and shows progress and the answer. A review's own fields are declared by the review
+ * service on `ReviewRunFields` (declaration merging), so the router carries them without reading them.
+ */
+/** Fields of a review's run, declared by the review service: `declare module ".../turn-runner.js" { interface ReviewRunFields { ... } }`. */
+export interface ReviewRunFields {
+}
+export interface TurnRun {
+    readonly conversation: Conversation;
+    /** The person the turn is for (whose approvals its cards are; Python `sender.aad_id`). */
+    readonly userId: string;
+    /** The person this turn acts for: their key, or an exchanged token. */
+    readonly credential: string;
+    readonly provider: CredentialProvider;
+    /** The session to continue; null: Claw creates one with this message. */
+    readonly sessionId: string | null;
+    /** What the person wrote (the session's title, the language of the answer). */
+    readonly text: string;
+    /** The message's id: the idempotency key of the send. */
+    readonly messageId: string;
+    readonly group: boolean;
+    readonly ownerName: string;
+    /** The model the session is pinned to ("" Claw's default). */
+    readonly model: string;
+    readonly fallbackModel: string;
+    /** The model the existing session is known to have ("" none known). */
+    readonly sessionModel: string;
+    /** The repository a NEW session is bound to (`/repo`); null: none. */
+    readonly repo: {
+        readonly url: string;
+        readonly branch: string;
+    } | null;
+    /** A card with what the session changed follows a finished answer. */
+    readonly showChanges: boolean;
+    /** The message(s) this one quotes, as text for the model ("" none). */
+    readonly quote: string;
+    /** `text` with the address behind each of its links ("" when it is `text`). */
+    readonly sent: string;
+    readonly files: readonly InboundFile[];
+    readonly lang: Lang;
+    /** The answer gets thumbs of the worker's own (a phone, whose own thumbs never reach the worker). */
+    readonly ownThumbs: boolean;
+    /** Claw pushes this person a run's end and its approvals. */
+    readonly notifies: boolean;
+    /** A review's own fields; undefined for a chat turn. */
+    readonly review: (ReviewRunFields & {
+        readonly kind: "review";
+    }) | undefined;
+}
+/** What the turn tells the router, and asks it, while it runs. */
+export interface TurnHooks {
+    /** Claw took the message: `sessionId` is the turn's session; `sessionModel` the model it now has. */
+    onSession(sessionId: string, sessionModel: string): void;
+    /** Claw is running this turn's message: a message queued behind it may go. */
+    onRunning(): void;
+    /** The turn's record: started, delivered (its answer is in the chat) or not. */
+    onTurn(sessionId: string, what: "started" | "delivered" | "failed", messageId: string): void;
+    stopRequested(): boolean;
+    /** The person pressed Deny on one of this turn's approval cards. */
+    toolDenied(): boolean;
+    /** Claw took this turn's stop: its failed end is the stop, not an error. */
+    stopConfirmed(): boolean;
+    /** The "Report a problem" card for a turn that went wrong; undefined: none. */
+    reportView(): OutMessage | undefined;
+}
+/** How a turn ended, as far as the router and a review read it. */
+export interface TurnOutcome {
+    readonly finalAnswer: string;
+}
+export interface TurnRunner {
+    run(run: TurnRun, hooks: TurnHooks): Promise<TurnOutcome>;
+    /**
+     * The answer of the session's last finished turn, read with `credential` (undefined: none finished yet). Claw refuses a
+     * session the credential does not own (a ClawError 401/403/404); one it cannot be reached for is a ClawUnreachable.
+     */
+    lastAnswer(credential: string, sessionId: string): Promise<string | undefined>;
+}

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

@@ -0,0 +1,81 @@
+import type { Lang } from "../locales/lang.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";
+/** What a waiting message gives the turn in front to start running in Claw (`_queue_behind`). */
+export declare const SUBMIT_WAIT_SECONDS = 15;
+/** 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;
+/** 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). */
+    readonly itemId: string;
+    /** The item's session (null: none yet). */
+    readonly itemSessionId: string | null;
+    /** The pull request, as `owner/repo#N`: a review is kept per pull request when it has no item. */
+    readonly pull: string;
+    /** The model it runs on ("" the worker's review model). */
+    readonly model: string;
+    /** Its request's language: a review's own lines follow it. */
+    readonly lang: Lang;
+    /** The review's own fields of the run. */
+    readonly fields: ReviewRunFields & {
+        readonly kind: "review";
+    };
+    /** The review's session exists (it is not the chat's: only the review remembers it). */
+    onSession(sessionId: string): void;
+    /** After the turn, unless it failed. */
+    after(outcome: TurnOutcome): Promise<void>;
+}
+/** A turn that was started: it runs on its own, and `done` settles when it is over (it never rejects). */
+export interface RunningTurn {
+    readonly done: Promise<void>;
+}
+export interface StartTurn {
+    readonly chat: Chat;
+    /** What the turn calls Claw with (for a review: the asker's identity token). */
+    readonly credential: string;
+    readonly text: string;
+    readonly messageId: string;
+    readonly clientPlatform: string;
+    readonly quote?: string;
+    readonly sent?: string;
+    readonly files?: readonly InboundFile[];
+    readonly review?: ReviewTurnStart;
+}
+/**
+ * Starting and following a turn (the Python `Agent._start_turn`, `_queue_behind`, `_guarded`, `_record_session`,
+ * `_record_turn`): a new task is admitted under the person's task limit; a message sent while the chat's turn runs is
+ * queued in Claw behind it (one at most); a review has a session of its own and is neither queued nor queued behind.
+ */
+export declare class TurnStarter {
+    private readonly ctx;
+    private readonly running;
+    constructor(ctx: RouterContext);
+    /** The turns that run now (a test waits for them). */
+    settled(): Promise<void>;
+    /** The turn that runs (its end is `done`), or undefined when none was started (the person was told why). */
+    start(request: StartTurn): Promise<RunningTurn | undefined>;
+    /** True when admitted as the chat's first turn; false when the chat has one (queue behind it); undefined: refused. */
+    private admit;
+    /**
+     * Registers `turn` behind the chat's running one; false (the person is told why) when it may not go. It is sent only
+     * once Claw runs the turn in front: then Claw names that turn as the one it waits behind.
+     */
+    private queueBehind;
+    private sessionOf;
+    private providerOf;
+    private ownThumbs;
+    /** What the run reads of the chat's session: its id, the model it has, the repository a new one is bound to. */
+    private sessionPart;
+    private runOf;
+    private hooks;
+    private guarded;
+    private tell;
+    /**
+     * The turn has a session: it is the chat's session, and a 1:1 chat remembers it for /sessions, with what a session
+     * this turn created was started with and the repository it is bound to (which uses up the `/repo` choice).
+     */
+    private recordSession;
+}

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

@@ -0,0 +1,104 @@
+import type { Lang } from "../locales/lang.js";
+import type { OutMessage, ViewButton } from "../ports/surface.js";
+import type { NoteButton, NoteFactory } from "./features.js";
+/**
+ * The cards of connecting and of the chat's own commands (the Python `render.link_card`, `binding_request_card`,
+ * `onboarding_card`, `repo_card`, `session_card`, `confirm_button`, `repo_button`, `show_button`), as view models the
+ * channel renders (`teams/src/views/commands/`). A model carries what the card says, never card JSON.
+ */
+/** Connect by confirming as `who` on the platform, or on the console page with `/link CODE`. */
+export interface LinkCardView {
+    readonly bot: string;
+    readonly who: string;
+    /** The console page that gives a `/link` code. */
+    readonly page: string;
+    readonly notice: string;
+}
+/** A one-time link to open and confirm, and the button to press after. */
+export interface BindingCardView {
+    readonly bot: string;
+    readonly confirmUrl: string;
+    /** A first sentence ("" none). */
+    readonly lead: string;
+    readonly notice: string;
+}
+/** A group member who has not connected: addressed to them, one button only they can use. */
+export interface OnboardingCardView {
+    readonly bot: string;
+    readonly name: string;
+    readonly channelUserId: string;
+    readonly promptId: string;
+    /** The steps are already in their 1:1 chat. */
+    readonly dmSent: boolean;
+    /** One extra line, for a card put back after someone else pressed its button ("" none). */
+    readonly note: string;
+    /** How long the request waits for them. */
+    readonly waitMinutes: number;
+}
+/** One repository `/repo` lists. */
+export interface RepoCardView {
+    readonly repo: string;
+    /** "" the default branch. */
+    readonly branch: string;
+    readonly lang: Lang;
+}
+/** One session `/sessions` lists. */
+export interface SessionCardView {
+    readonly sessionId: string;
+    /** What it was started with ("" none known). */
+    readonly title: string;
+    readonly repo: string;
+    readonly branch: string;
+    /** When it was last used here, as the person reads it ("today 12:40"). */
+    readonly when: string;
+    /** It is this chat's session now. */
+    readonly current: boolean;
+    readonly lang: Lang;
+    /** The console's address. */
+    readonly publicBaseUrl: string;
+}
+declare module "../ports/surface.js" {
+    interface ViewMap {
+        link: LinkCardView;
+        binding: BindingCardView;
+        onboarding: OnboardingCardView;
+        repo: RepoCardView;
+        session: SessionCardView;
+    }
+}
+/** Minutes a group request waits for its asker to connect (the store keeps it as long). */
+export declare const ONBOARDING_REQUEST_MINUTES = 15;
+/** The Confirm button of the older connect card (the person says they confirmed). */
+export declare const CONFIRM_BUTTON: NoteButton;
+/** The button a `/repo` card and its notes carry; it comes back from the client, so it is read again like typed text. */
+export declare function repoButton(repo: string, branch: string, lang?: Lang): NoteButton;
+/** The Show here button: it makes a session this chat's session again. */
+export declare function showButton(sessionId: string, title?: string): NoteButton;
+/** A Create PR button, under the changes card and on the notes that put it back (Python `create_pr_button`). */
+export declare function createPrButton(sessionId: string): NoteButton;
+/**
+ * A note button as the worker's click protocol carries it, field for field as the Python worker's `confirm_button`,
+ * `repo_button`, `show_button` and `create_pr_button` build it: the verb `primusclaw.<kind>`, and the data naming the
+ * kind first (`primusclaw: <kind>`), which is what a press is routed by.
+ */
+export declare function viewButtonOf(button: NoteButton): ViewButton;
+/**
+ * The note card the router's clicks end as (Python `render.note_card(text, buttons, title, tone)`): what assembly passes
+ * as `RouterDeps.note`. A tone the note does not know is the default one.
+ */
+export declare const noteFactory: NoteFactory;
+/** Builds the messages of the router's cards. */
+export declare class CommandViews {
+    private readonly bot;
+    private readonly publicBaseUrl;
+    readonly note: NoteFactory;
+    constructor(bot: string, publicBaseUrl: string, note: NoteFactory);
+    link(who: string): OutMessage;
+    binding(confirmUrl: string, lead?: string): OutMessage;
+    onboarding(member: {
+        name: string;
+        channelUserId: string;
+    }, promptId: string, dmSent: boolean, note?: string): OutMessage;
+    repo(repo: string, branch: string, lang: Lang): OutMessage;
+    session(card: Omit<SessionCardView, "publicBaseUrl">): OutMessage;
+}

package/dist/types/security/redact-scan.d.ts

@@ -0,0 +1,19 @@
+/** What a masked value is replaced with. */
+export declare const MASK = "[hidden]";
+/**
+ * The JWT rule. A start that fails fails for every later "eyJ" inside the same first part (they share its end, the
+ * dot and the parts after it, and have fewer characters before the dot), so the scan goes on after that part.
+ */
+export declare function maskJwts(text: string): {
+    text: string;
+    masked: boolean;
+};
+/**
+ * The secret rule: only the value is masked (the name, the separator and a quote stay). A name that fails fails for
+ * every later name in the same run of word characters (its `[\w-]*` reaches every place theirs can), so the scan goes
+ * on after that run.
+ */
+export declare function maskSecretValues(text: string): {
+    text: string;
+    masked: boolean;
+};

package/dist/types/security/redact-text.d.ts

@@ -0,0 +1,14 @@
+import { MASK } from "./redact-scan.js";
+export { MASK };
+/**
+ * The one line a channel adds to a message it masked (the Python worker's text, byte for byte). Masking an outbound
+ * activity or card is the channel's (the Teams package's), with `redactText` and this note.
+ */
+export declare const NOTE = "Some sensitive-looking values were hidden. Ask me in a 1:1 chat if you need them.";
+/** `text` with credential-shaped values masked, and whether anything was masked. */
+export declare function redactText(text: string): {
+    text: string;
+    masked: boolean;
+};
+/** A log line with credential shapes masked, and the values of credential-named URL query parameters. */
+export declare function redactLogLine(text: string): string;