@primusclaw/personal-agent 0.0.0-stage → 0.1.0

package/dist/types/assistant/receipts.d.ts

@@ -0,0 +1,71 @@
+import type { Lang } from "../locales/lang.js";
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { Conversation, Envelope, MessageId, OutMessage, UpdateOptions } from "../ports/surface.js";
+import { Receipt, type ReceiptStream } from "./receipt.js";
+/** Opens a live stream under the message being answered with `status` as its first update; undefined where none can be. */
+export type ReceiptOpener = (status: string) => Promise<ReceiptStream | undefined>;
+export declare class Receipts {
+    private readonly clock;
+    private readonly log;
+    /** The reply style has receipts on (`assistant_receipt`). */
+    private readonly enabled;
+    private readonly open;
+    constructor(clock: Clock, log: Logger, 
+    /** The reply style has receipts on (`assistant_receipt`). */
+    enabled?: () => boolean);
+    /**
+     * Open the assistant's receipt in `conversation`. Undefined when there is none (receipts off, one already open, no stream here,
+     * or the channel refused it): the caller shows the typing indicator.
+     */
+    openIn(conversation: string, lang: Lang, opener: ReceiptOpener): Promise<Receipt | undefined>;
+    /** The worker stops: every open receipt is dropped (`Receipt.drop`), so no close timer or follower keeps the process up. */
+    stop(): void;
+    /** The open receipt of this conversation, left where it is (what follows the turn shows its steps in it). */
+    openOf(conversation: string): Receipt | undefined;
+    /**
+     * The open receipt of this conversation, taken (the first reply closes it). One kept for a handed-back review's answer is
+     * taken only by that answer (`reserved`). `reply`: what the assistant said, pushed by Claw, said by the turn `reply.turn`; one
+     * that is not the message's own reply leaves the receipt where it is (`Receipt.answeredBy`), as does one that is no turn's
+     * answer at all (`reply.foreign`: a task's own notice). The worker's own words in the receipt's place (the message was not
+     * taken) pass no `reply` and always take it.
+     */
+    take(conversation: string, reserved?: Receipt, reply?: {
+        readonly turn?: string | undefined;
+        readonly foreign?: boolean;
+    }): Receipt | undefined;
+    /** Keep the open receipt for the answer to a review handed back for the message `replyTo` (only the receipt under it). */
+    reserve(conversation: string, replyTo: MessageId): Receipt | undefined;
+}
+/**
+ * `message` (a text message) with what the assistant said beside it added at its end, after "另外：" ("Also: " when nothing is
+ * Chinese).
+ */
+export declare function withPostscript(message: OutMessage, said: readonly string[]): OutMessage;
+/**
+ * A conversation whose first text message closes `receipt` in its place under the person's message: the answer to a review the
+ * assistant handed back is the one reply to it. A view, and a first message the channel does not take there, are messages of
+ * their own. What the assistant said beside the handoff (`postscript`) is added to the first text message.
+ */
+export declare class ReceiptConversation implements Conversation {
+    private readonly inner;
+    private readonly receipts;
+    private receipt;
+    private postscript;
+    constructor(inner: Conversation, receipts: Receipts, receipt: Receipt | undefined, postscript?: readonly string[]);
+    get ref(): import("../ports/surface.js").ConversationRef;
+    get edited(): ReadonlySet<string>;
+    markSettled(id: MessageId): void;
+    typing(): Promise<void>;
+    send(message: OutMessage): Promise<void>;
+    post(message: OutMessage): Promise<MessageId | undefined>;
+    update(id: MessageId, message: OutMessage, options?: UpdateOptions): Promise<void>;
+    delete(id: MessageId): ReturnType<Conversation["delete"]>;
+    outgoing(message: OutMessage): Envelope;
+    deliver(envelope: Envelope): Promise<void>;
+    openStream(replyTo: MessageId, status: string): ReturnType<Conversation["openStream"]>;
+    /** What the assistant said beside the handoff, when no text message carried it: said on its own. */
+    sayPostscript(): Promise<void>;
+    /** Nothing was said: the receipt is no longer kept, so a reply of the assistant (or its own limit) closes it. */
+    release(): void;
+}

package/dist/types/assistant/say.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The messages for an `assistant.say` or `work_item.needs_you` event, in order (teams_agent/assistant.py `say_activities`).
+ *
+ * - What was said, whole and once: a long text is split into up to three messages at paragraph breaks, never cut, after what the
+ *   receipt already shows of it (`shown`). It is an AI answer: the AI label and the thumbs under it, a citation for each source it
+ *   cites as [n], and the replies to tap under the last of its messages when no card follows.
+ * - When the event's item holds a result that waits, a card with Accept and Stop; when it holds a write for the person, a card
+ *   that lets it through or not; when it puts a command to the person, a card with Run and Cancel (each recorded first, so its
+ *   buttons mean something). A card holds the words only when they are short and not shown already.
+ * - Then a card for each file the item's worker delivered, with Claw's own download link.
+ *
+ * Every word of this worker's own is in the person's language, never in that of what was said.
+ */
+import type { SuggestedReply } from "../direct-chat/direct-chat.js";
+import type { StorePort } from "../ports/store/index.js";
+import type { OutMessage } from "../ports/surface.js";
+export type SayStore = Pick<StorePort, "prefs" | "assistantCards" | "assistantButtons">;
+/** (worker session, delivery id) -> Claw's download link, or null. */
+export type DeliveryLink = (sessionId: string, deliveryId: string) => string | null;
+export interface SayOptions {
+    readonly linkFor?: DeliveryLink | undefined;
+    /** What the receipt already shows of the words. */
+    readonly shown?: string;
+    /** The first line of what is said (direct chat: Clawy's head). */
+    readonly head?: string;
+    /** Suggested replies of the worker's own, before Claw's. */
+    readonly replies?: readonly SuggestedReply[];
+}
+export interface SayDeps {
+    readonly store: SayStore;
+    /** The router's test of a command typed whole (for a command the assistant puts to the person). */
+    readonly exactCommand: (text: string) => boolean;
+    /** The reply style's switches: citations and suggested replies under what the assistant said. */
+    readonly style: () => {
+        readonly citations: boolean;
+        readonly suggestedReplies: boolean;
+    };
+    /** The locale of the client the message being handled came from ("" none). */
+    readonly clientLocale?: () => string;
+}
+type Event = Readonly<Record<string, unknown>>;
+export declare class SayPlanner {
+    private readonly deps;
+    constructor(deps: SayDeps);
+    /** The messages for `event` to `userId`, in order; [] when the event says nothing. */
+    messages(userId: string, event: Event, options?: SayOptions): OutMessage[];
+    /** What is said: the event's words (or that its item needs the person), under `head`; the files' names when nothing else says. */
+    private words;
+    /** A card for each delivered file Claw gives a link for, and the names of all of them. */
+    private fileCards;
+    /** The replies to tap, under the last of what was said, when no card follows. */
+    private withReplies;
+    /**
+     * The card with buttons the event asks for, recorded first: a result that waits, a write Claw holds, or a command put to the
+     * person; undefined for none. `holdsWords`: the card shows the words, which are then not said apart.
+     */
+    private card;
+    /** What was said, as AI answers with thumbs, each with the citations its own words cite (when the whole text cites at all). */
+    private said;
+    /** A result that waits: Accept and Stop, and (a task whose result names a pull request) auto-reply on or off. */
+    private workCard;
+}
+export {};

package/dist/types/assistant/tracked-stream.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Core's wrapper over the Surface's `LiveStream`: what the receipt tracks about a stream (the text streamed so far, its age,
+ * whether a final was sent) is kept here, not by the port. The stream's own message id comes from the port: a final the channel
+ * refuses is edited into that message, and what the turn amends or replaces after the stream closed edits it too.
+ */
+import type { Clock } from "../ports/clock.js";
+import type { Conversation, LiveStream, MessageId, OutMessage, StreamRefused, UpdateOptions } from "../ports/surface.js";
+import type { Result } from "../result.js";
+import type { ReceiptStream } from "./receipt.js";
+export declare class TrackedStream implements ReceiptStream {
+    private readonly live;
+    private readonly conversation;
+    readonly replyTo: MessageId;
+    private readonly clock;
+    open: boolean;
+    streamed: string;
+    readonly streamId: MessageId;
+    private readonly started;
+    constructor(live: LiveStream, conversation: Conversation, replyTo: MessageId, clock: Clock);
+    /** A final may still be refused and then edited into place: the channel gave the stream an id and it was not closed. */
+    get closable(): boolean;
+    ageSeconds(): number;
+    inform(text: string, options?: UpdateOptions): Promise<Result<void, StreamRefused>>;
+    emit(text: string, options?: UpdateOptions): Promise<Result<void, StreamRefused>>;
+    final(message: OutMessage): Promise<Result<void, StreamRefused>>;
+    update(id: MessageId, message: OutMessage): Promise<void>;
+    delete(id: MessageId): Promise<void>;
+}
+/** Opens the receipt's stream under the person's message `replyTo` in `conversation` (`Receipts.openIn`'s opener). */
+export declare function streamOpener(conversation: Conversation, replyTo: MessageId, clock: Clock): (status: string) => Promise<ReceiptStream | undefined>;

package/dist/types/assistant/turn-in-front.d.ts

@@ -0,0 +1,25 @@
+import type { ClawSessionsPort } from "../ports/claw/index.js";
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { Receipt } from "./receipt.js";
+/** How long the turn in front of a message is waited for; later, the receipt does without (the first reply closes it). */
+export declare const FRONT_TURN_SECONDS = 2;
+export interface TurnInFrontDeps {
+    readonly sessions: Pick<ClawSessionsPort, "turn">;
+    readonly clock: Clock;
+    readonly logger: Logger;
+}
+export declare class TurnInFront {
+    private readonly deps;
+    private abandoned;
+    private readonly read;
+    /** Starts reading which turn holds `sessionId` now: its message id while it runs, else none. */
+    constructor(deps: TurnInFrontDeps, credential: string, sessionId: string);
+    /**
+     * The turn read, just before the message is sent: undefined when this message has no receipt, the session was idle, or Claw
+     * did not say within FRONT_TURN_SECONDS (the receipt is then closed by the first reply, as before).
+     */
+    before(receipt: Receipt | undefined): Promise<string | undefined>;
+    /** The message went (or never will): whatever the read still brings is not wanted. */
+    abandon(): void;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * The assistant's views: a work item that waits for the person, what replaces it once pressed, the board, a command or a write
+ * put to the person (the arguments of teams_agent/render.py work_card, work_done_card, note_card with
+ * work_buttons, board_card with board_buttons, action_card and confirm_write_card, one for one).
+ */
+import type { ReviewAskedOfOther, WorkItem } from "../claw/model.js";
+/** A work item that waits for the person (render.work_card). */
+export interface WorkCardModel {
+    readonly item: WorkItem;
+    /** What the assistant said about it ("" none). */
+    readonly text: string;
+    /** The card the worker recorded; the buttons carry only its id. */
+    readonly cardId: string;
+    /** One bold line when the card replaces an older one ("" none). */
+    readonly note: string;
+    /** Offer "Auto-reply to PR comments" (a task whose result is a pull request). */
+    readonly watch: boolean;
+    /** Auto-reply is on: offer to turn it off instead. */
+    readonly watching: boolean;
+    /** "zh" or "en"; null to follow what was said, or the item's title. */
+    readonly lang: string | null;
+}
+/** What replaces a work card after Accept or Stop went through (render.work_done_card). */
+export interface WorkDoneModel {
+    /** "Accepted" (the version is said), or how it ended otherwise. */
+    readonly verb: string;
+    readonly item: WorkItem;
+}
+/** A work card put back after a press that did not go through: the note, then its buttons again (note_card + work_buttons). */
+export interface WorkNoteModel {
+    readonly text: string;
+    readonly cardId: string;
+    readonly version: number;
+    readonly canAccept: boolean;
+}
+/** A task the board offers to run again, with the card recorded for its button. */
+export interface BoardRetry {
+    readonly cardId: string;
+    readonly item: WorkItem;
+}
+/** The person's board (render.board_card, its buttons render.board_buttons). */
+export interface BoardModel {
+    readonly items: readonly WorkItem[];
+    /** The reviews the person asked of others, shown beside their own. */
+    readonly asked: readonly ReviewAskedOfOther[];
+    /** Epoch seconds: how long ago each item changed is counted from here. */
+    readonly now: number;
+    /** The cards recorded for the results that wait (Accept all; none: no button). */
+    readonly accept: readonly string[];
+    /** Tasks that failed or were stopped (Retry each, within a card's three buttons). */
+    readonly retry: readonly BoardRetry[];
+    /** "zh" or "en"; null to follow the items' titles. */
+    readonly lang: string | null;
+}
+/** A command the assistant put to the person instead of running it (render.action_card). */
+export interface ActionCardModel {
+    readonly text: string;
+    readonly cardId: string;
+    readonly command: string;
+    /** "zh" or "en"; null to follow what was said. */
+    readonly lang: string | null;
+}
+/** A write Claw holds until the person answers (render.confirm_write_card). */
+export interface ConfirmWriteModel {
+    readonly text: string;
+    readonly cardId: string;
+    /** Claw's word for letting it through ("" for "Confirm"). */
+    readonly allowLabel: string;
+    readonly lang: string;
+}
+declare module "../ports/surface.js" {
+    interface ViewMap {
+        actionCard: ActionCardModel;
+        board: BoardModel;
+        confirmWrite: ConfirmWriteModel;
+        workCard: WorkCardModel;
+        workDone: WorkDoneModel;
+        workNote: WorkNoteModel;
+    }
+}

package/dist/types/assistant/watch-clicks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * "Auto-reply to PR comments" and "Turn off auto-reply" under a task's card (teams_agent/assistant.py `_watch`, `_unwatch`).
+ *
+ * Turning it on watches the pull request the item's worker reported (Claw's own record, never a link the card's words name) with
+ * replies allowed, asked as the person signed in (their exchanged token: Claw takes `reply` from nobody else). Turning it off
+ * stops every pull request the item watches, asked with the linked key (taking away needs only ownership). The card is put back
+ * as it was, and the outcome is said.
+ */
+import type { CardClick } from "../approvals/click.js";
+import type { ClawWorkItemsPort } from "../ports/claw/index.js";
+import type { Logger } from "../ports/logger.js";
+import type { StorePort } from "../ports/store/index.js";
+import type { TokenExchange } from "../plugins/token-exchange.js";
+export interface WatchClickDeps {
+    readonly store: Pick<StorePort, "assistantCards">;
+    readonly claw: Pick<ClawWorkItemsPort, "pulls" | "watches" | "watchPull" | "unwatchPull">;
+    /** The identity service's token exchange; disabled: answering on GitHub for the person is not offered. */
+    readonly exchange: TokenExchange;
+    readonly logger: Logger;
+}
+export declare class WatchClicks {
+    private readonly deps;
+    constructor(deps: WatchClickDeps);
+    private card;
+    /** The card again (when it is still open and the item still waits) with what was said under it, else the words alone. */
+    private putBack;
+    watch(click: CardClick, key: string): Promise<void>;
+    private turnOn;
+    /** The person's exchanged token; undefined when they are not connected through the identity service. */
+    private token;
+    /** Whether the item already answers new comments on `pull` unasked; false when Claw cannot be read. */
+    private wasOn;
+    unwatch(click: CardClick, key: string): Promise<void>;
+}

package/dist/types/assistant/work-clicks.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Presses on Accept and Stop under a work item's card, and on the board's Accept all and Retry (teams_agent/assistant.py
+ * `on_click`, `_retry`, `_accept_all`). Cards are not trusted: a button carries the id of the card this worker recorded, and
+ * what it means is read from the record; it must be the presser's and not yet used, and of two presses exactly one goes on.
+ * Claw is asked as the presser. Accept is pinned to the version the person saw: a newer one gets a card of its own.
+ */
+import type { CardClick } from "../approvals/click.js";
+import type { WorkItem } from "../claw/model.js";
+import type { ClawWorkItemsPort } from "../ports/claw/index.js";
+import type { StorePort } from "../ports/store/index.js";
+import type { Board } from "./board.js";
+export type WorkClickStore = Pick<StorePort, "now" | "assistantCards">;
+export interface WorkClickDeps {
+    readonly store: WorkClickStore;
+    readonly claw: Pick<ClawWorkItemsPort, "get" | "accept" | "stop" | "retry">;
+    readonly board: Board;
+    /** An item was stopped here: whatever follows its work here ends as stopped. */
+    readonly onStopped: (itemId: string) => void;
+}
+/** What a refusal from Claw means for a person who pressed a button. */
+export declare function failureText(status: number, code: string): string;
+/** Where an item stands, for a press that arrived too late (or too early) to do what its card offered. */
+export declare function statusText(item: WorkItem): string;
+export declare class WorkClicks {
+    private readonly deps;
+    constructor(deps: WorkClickDeps);
+    /** The card is the presser's and open, and this press now holds it ("busy"): of two presses exactly one goes on. */
+    private take;
+    private card;
+    /** Accept or Stop under a work item's card. */
+    acceptOrStop(click: CardClick, key: string, op: "accept" | "stop"): Promise<void>;
+    /** Nothing was done: a 404 ends the card; anything else offers it again, as a new message that can be pressed. */
+    private notDecided;
+    private decided;
+    /** The outcomes of a review's stop, and a merge that cannot be stopped; false when the decision is none of them. */
+    private reviewOutcome;
+    /** The result changed after the card was made: nothing was accepted, and a card for the current result is sent. */
+    private newerVersion;
+    /**
+     * Retry on the board: the task (failed, or stopped) runs again in its own session; Claw decides whether it may. A stopped task
+     * is read first: past RETRY_STOPPED_SECONDS its Retry has expired, as the board would no longer offer it, and Claw is not asked.
+     */
+    retry(click: CardClick, key: string): Promise<void>;
+    /** A Retry pressed after the stop it was drawn for has aged past RETRY_STOPPED_SECONDS: the card is done, Claw is not asked. */
+    private retryExpired;
+    private retryFailed;
+    /**
+     * Accept all on the board: each result it listed, at the version it showed (one card each); a result that changed since, or a
+     * card already used, is left for its own card. One line says what was accepted.
+     */
+    acceptAll(click: CardClick, key: string): Promise<void>;
+    private acceptOne;
+}

package/dist/types/assistant/work-handler.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The buttons of work item cards and of the board, for the router (teams_agent/agent.py `_dispatch`, `Assistant.on_click`). A
+ * person with no linked key (their review runs on someone else's) presses with their exchanged token instead.
+ */
+import type { Logger } from "../ports/logger.js";
+import type { ClickHandler, ClickRoute } from "../ports/routing.js";
+import type { TokenExchange } from "../plugins/token-exchange.js";
+import type { WatchClicks } from "./watch-clicks.js";
+import type { WorkClicks } from "./work-clicks.js";
+export declare class WorkCardClicks implements ClickHandler {
+    private readonly work;
+    private readonly watch;
+    private readonly exchange;
+    /** Whether the person has a linked key. */
+    private readonly linked;
+    private readonly logger;
+    readonly verbs: readonly ["work"];
+    constructor(work: WorkClicks, watch: WatchClicks, exchange: TokenExchange, 
+    /** Whether the person has a linked key. */
+    linked: (userId: string) => boolean, logger: Logger);
+    beforeCredential(click: ClickRoute): Promise<boolean>;
+    withCredential(click: ClickRoute, credential: string): Promise<void>;
+}

package/dist/types/assistant/work-items.d.ts

@@ -0,0 +1,66 @@
+/**
+ * What the assistant says about a work item, in words any channel shows (teams_agent/render.py item_label, card_paragraphs,
+ * fits_work_card, work_event_text, retryable, board_line, _board_detail, _board_meaning, _ago, asked_line, _asked_meaning and the
+ * translation in asked_section). The cards that carry these words are the channel's; these are its pure helpers.
+ */
+import type { ReviewAskedOfOther, AskerView, WorkItem } from "../claw/model.js";
+import type { Lang } from "../locales/lang.js";
+/** What the assistant may say at most (Claw refuses a longer one); a card shows all of it. */
+export declare const WORK_TEXT_MAX = 600;
+/** Items listed per section of the board; the rest is one "and N older" line. */
+export declare const BOARD_LINES = 8;
+/** Items waiting for the person that get a card of their own under the board, at most. */
+export declare const BOARD_CARDS = 5;
+/** Retry buttons on the board, beside Accept all within a card's three: tasks that failed or were stopped, newest first. */
+export declare const BOARD_RETRY_MAX = 3;
+/**
+ * A stopped task offers Retry only this long after it was stopped. Every stop is the person's own (the Stop button, or the
+ * assistant asked to), and the board lists what ended in the last seven days: past this, Retry would keep offering, for days, to
+ * undo a decision the person made on purpose. A failed task waits on the person (needs_you) and keeps its Retry while it waits.
+ */
+export declare const RETRY_STOPPED_SECONDS = 3600;
+/** Rows a section of the board shows; the rest of BOARD_LINES opens in place. */
+export declare const BOARD_SHOWN: Readonly<Record<string, number>>;
+/** The longest title line a card has (the card kit's TITLE_MAX). */
+export declare const LABEL_MAX = 120;
+/** The longest detail on a board row (a question asked, a progress report). */
+export declare const DETAIL_MAX = 80;
+/** `text` for a card's markdown: its markup characters escaped, so that `__init__.py` is not bold (render._plain). */
+export declare function markdownPlain(text: string): string;
+/** `lang` when it is "zh" or "en", else the language of the first of `texts` that says anything (`pickLang`). */
+export declare function cardLang(lang: string | null | undefined, ...texts: unknown[]): Lang;
+/** `#seq title`, one line. */
+export declare function itemLabel(item: Pick<WorkItem, "seq" | "title">): string;
+/** `text` with every line its own paragraph (a card runs lines that are separated by one newline together). */
+export declare function cardParagraphs(text: string): string;
+/** Whether a work item's card shows all of `text` (as its card lays it out), not clipped. */
+export declare function fitsWorkCard(text: string): boolean;
+/** `text` as a work card shows it (`cardParagraphs`), cut to `limit` with an ellipsis. */
+export declare function workCardText(text: string, limit?: number): string;
+/** What an assistant event says: its own text, or (a fallback notice carries none) that the item needs the person. */
+export declare function workEventText(item: WorkItem | null, text: unknown): string;
+/**
+ * A task Claw runs again on Retry (`POST /v1/work-items/:id/retry`): its worker reported failed, or it was stopped in the last
+ * RETRY_STOPPED_SECONDS before `now` (seconds since the epoch). A stop whose time (`updatedAt`) is not known is not offered.
+ */
+export declare function retryable(item: WorkItem, now: number): boolean;
+/** What matters about an item in its section: what it waits for, or the progress its worker last reported; "" for a done one. */
+export declare function boardDetail(item: WorkItem, lang: Lang): string;
+/** One item on the board as a line of text: `#2 title`, and what matters about it in its column. */
+export declare function boardLine(item: WorkItem, lang?: Lang): string;
+/** The status of a row on the board, as the card kit's meanings name it. */
+export type RowMeaning = "good" | "stopped" | "dropped" | "needs_you" | "question" | "failed" | "review" | "working" | "handoff";
+/** The emoji of an item's row: what state it is in, at a glance. */
+export declare function boardMeaning(item: WorkItem): RowMeaning;
+/** How long ago Claw last changed an item (`updatedAt`, ISO 8601), short: "5 分钟前" / "5 min ago"; "" when not known. */
+export declare function ago(at: string, now: number, lang: Lang): string;
+/** The review is over (Claw no longer lists it as open). */
+export declare function askerFinished(view: AskerView): boolean;
+/** The review waits for its reviewer (a confirmation, a retry, their start). */
+export declare function askerWaits(view: AskerView): boolean;
+/** One review asked of someone else: the pull request, who reviews it, and how it stands (the asker's view only), in English. */
+export declare function askedLine(asked: ReviewAskedOfOther): string;
+/** The emoji of an asked review's row. */
+export declare function askedMeaning(asked: ReviewAskedOfOther): RowMeaning;
+/** An asked review's line split for a board row: (the pull request and its reviewer, how it stands in `lang`). */
+export declare function askedRow(asked: ReviewAskedOfOther, lang: Lang): readonly [string, string];

package/dist/types/branding.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The user-visible name of the bot. A deployment may name it otherwise (the router's `botName`); every text that names
+ * the bot takes the name it is given, and this is the default.
+ */
+export declare const BOT_NAME = "Clawy";

package/dist/types/brief/brief.d.ts

@@ -0,0 +1,40 @@
+import type { JsonObject } from "../json.js";
+import type { ClawAssistantPort } from "../ports/claw/assistant.js";
+import type { ClawTriggersPort } from "../ports/claw/settings.js";
+import type { Logger } from "../ports/logger.js";
+import type { CommandHandler, CommandRoute } from "../ports/routing.js";
+import type { LinkRepository } from "../ports/store/link.js";
+import type { PrefsRepository } from "../ports/store/people.js";
+/**
+ * `/brief`: the daily brief. `/brief on [HH:MM]` makes (or refreshes) the person's weekday trigger in their time zone,
+ * `/brief off` removes it, `/brief` says whether it is on, and with the assistant `/brief` and `/brief now` show the brief
+ * itself, put together by Claw at once. A trigger keeps a copy of the key it was made with, so it must be the person's
+ * own linked key, never an exchanged token.
+ */
+export interface BriefDeps {
+    /** Off until Claw's trigger API is deployed: the command then says so. */
+    readonly enabled: boolean;
+    readonly links: Pick<LinkRepository, "getKey">;
+    readonly prefs: Pick<PrefsRepository, "getPrefs" | "setBriefTrigger">;
+    readonly triggers: ClawTriggersPort;
+    readonly assistant: Pick<ClawAssistantPort, "brief">;
+    /** A 1:1 chat that talks to the person's assistant. */
+    readonly assistantOn: (userId: string) => boolean;
+    /** The brief Claw answered, as the message that shows it (the assistant's view of it). */
+    readonly briefMarkdown: (brief: JsonObject) => string;
+    readonly log: Logger;
+}
+export declare class DailyBrief implements CommandHandler {
+    private readonly deps;
+    readonly name = "brief";
+    constructor(deps: BriefDeps);
+    run(route: CommandRoute, args: string): Promise<boolean>;
+    private dispatch;
+    /** The person's brief trigger: the one recorded, else one of the brief's name. */
+    private find;
+    private state;
+    /** The brief itself, now, as one message; `/brief` adds whether it comes on its own, `/brief now` is the brief alone. */
+    private showNow;
+    private turnOn;
+    private turnOff;
+}

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

@@ -0,0 +1,3 @@
+export { briefText } from "../locales/brief.js";
+export * from "./brief.js";
+export * from "./template.js";

package/dist/types/brief/template.d.ts

@@ -0,0 +1,8 @@
+/** The daily brief's scheduled trigger (the Python worker's `templates/daily-brief.json`). */
+export declare const DAILY_BRIEF: {
+    readonly name: "Daily brief";
+    readonly defaultTime: "08:30";
+    /** Weekdays, as cron's day-of-week field. */
+    readonly days: "1-5";
+    readonly prompt: string;
+};

package/dist/types/capabilities/capability.d.ts

@@ -0,0 +1,49 @@
+/** The shape of one entry of the capability registry (`registry.ts`). */
+export type CategoryKey = "chat" | "review" | "settings" | "remote" | "notify" | "feedback";
+export interface Category {
+    readonly key: CategoryKey;
+    readonly zh: string;
+    readonly en: string;
+}
+/** In the order help shows them. */
+export declare const CATEGORIES: readonly Category[];
+/** Where help shows a capability: a 1:1 chat, a group chat, or both. */
+export type Where = "dm" | "group" | "both";
+/** "assistant" only with the assistant on, "session" only without it, "understanding" only for the people the assistant
+ * understands every message of, "" either way. */
+export type CapabilityMode = "" | "assistant" | "session" | "understanding";
+/** The parts of the worker a capability needs on: shown only then. */
+export type Part = "github" | "remote" | "brief" | "schedule" | "watch_job";
+export interface Capability {
+    readonly key: string;
+    /** A CATEGORIES key; "" for help itself (the closing line, not a category). */
+    readonly category: CategoryKey | "";
+    /** What it is, in a few words. */
+    readonly zh: string;
+    readonly en: string;
+    /** One sentence a person would type for it ("" : it is done with buttons). */
+    readonly sayZh: string;
+    readonly sayEn: string;
+    /**
+     * Where the example goes: "turn", "group_review [MODEL]" (one review per pull request it names), "review_mode MODE" (the card
+     * to choose it), "unlink_ask", or "<command> [ARG]" as the worker reads it.
+     */
+    readonly reaches: string;
+    /** The code's surfaces it stands for: command:, github:, agent:, card:, setting:, route:. */
+    readonly covers: readonly string[];
+    readonly where: Where;
+    /** Where its example is typed: "dm", or "group" (after an @mention). */
+    readonly typedIn: "dm" | "group";
+    readonly mode: CapabilityMode;
+    /** Whose current value help shows (a key of the `values` help is given). */
+    readonly setting: string;
+    readonly needs: Part | "";
+    /**
+     * The assistant may ask the chat to do it (`channelActions`): its command, carried out as if typed. Never one that cannot be
+     * undone or that loosens a safety setting (`NOT_ACTIONS`).
+     */
+    readonly action: boolean;
+}
+type Fields = Pick<Capability, "key" | "category" | "zh" | "en"> & Partial<Capability>;
+export declare function capability(fields: Fields): Capability;
+export {};

package/dist/types/capabilities/command-text.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The longest message, as it is read (stripped, its closing punctuation off; in characters, as Python's `len`), that is read
+ * for a command said in plain words or a switch to an agent's session. A longer one is no sentence of help's and goes on as
+ * the words it is: no pattern runs over it, so no message can make the reading slow (the Python worker's
+ * MAX_COMMAND_TEXT_CHARS). A feedback sentence ("反馈：…") is read before this is checked, so a long one is still /feedback.
+ */
+export declare const MAX_COMMAND_TEXT_CHARS = 1000;
+/** The same for a sentence about the sessions themselves (`sessionControl`; the Python worker's MAX_SESSION_CONTROL_CHARS). */
+export declare const MAX_SESSION_CONTROL_CHARS = 160;
+/** `flat` (a message as it is read) is no longer than `most` characters. */
+export declare function within(flat: string, most: number): boolean;

package/dist/types/capabilities/entries-chat.d.ts

@@ -0,0 +1,3 @@
+import { type Capability } from "./capability.js";
+/** The registry's entries for chat and tasks, reviews and merges, in the order help shows them. */
+export declare const CHAT_ENTRIES: readonly Capability[];

package/dist/types/capabilities/entries-notify.d.ts

@@ -0,0 +1,3 @@
+import { type Capability } from "./capability.js";
+/** The registry's entries for notifications, feedback and help itself, in the order help shows them. */
+export declare const NOTIFY_ENTRIES: readonly Capability[];

package/dist/types/capabilities/entries-settings.d.ts

@@ -0,0 +1,3 @@
+import { type Capability } from "./capability.js";
+/** The registry's entries for settings and remote agents, in the order help shows them. */
+export declare const SETTINGS_ENTRIES: readonly Capability[];

package/dist/types/capabilities/help.d.ts

@@ -0,0 +1,24 @@
+import { type Lang } from "../locales/lang.js";
+import { type Part } from "./registry.js";
+export declare const CURRENT_WORDS: Readonly<Record<Lang, string>>;
+/** A confirmation setting as help says it: [Chinese, English]. */
+export declare const CONFIRM_MODE_WORDS: Readonly<Record<string, readonly [string, string]>>;
+/**
+ * The paragraph of help that says what the bot can do and as whom (security review): every action is someone's own, what waits
+ * for a person's tap, and that the taps that add authority are limited per person. The review and remote-agent sentences only when
+ * those parts are on.
+ */
+export declare function authorityText(zh: boolean, parts?: ReadonlySet<Part>): string;
+export interface HelpOptions {
+    readonly group?: boolean;
+    readonly assistant?: boolean;
+    readonly parts?: ReadonlySet<Part>;
+    /** This person's settings as help shows them ("当前：..."), by a capability's `setting`. */
+    readonly values?: Readonly<Record<string, string>>;
+    /** Goes first: which account, where the chat is attached. */
+    readonly lead?: string;
+    readonly bot?: string;
+    readonly understanding?: boolean;
+}
+/** The help for a chat, in `language` ("zh", or anything else for English). */
+export declare function renderHelp(language: string, options?: HelpOptions): string;