@primusclaw/personal-agent 0.0.0-stage → 0.1.0

package/dist/types/feedback/service.d.ts

@@ -0,0 +1,74 @@
+import type { FeedbackSink } from "../plugins/feedback-sink.js";
+import type { ClawSessionsPort } from "../ports/claw/sessions.js";
+import { type Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { FeedbackRepository } from "../ports/store/feedback.js";
+import type { LinkRepository } from "../ports/store/link.js";
+import { FeedbackDelivery, type ReportDeliveryKind } from "./delivery.js";
+import { type TurnText } from "./exchange.js";
+import { type IssueWording, type Mask } from "./issue-text.js";
+import { type Scene } from "./scene.js";
+import type { FeedbackOfferView, FeedbackReportView } from "./views.js";
+/** What the deployment says about itself in a report (image tags read at start; "" when not said). */
+export interface WorkerInfo {
+    readonly pluginId: string;
+    readonly version: string;
+    readonly workerImage: string;
+    readonly apiImage: string;
+    readonly brainImage: string;
+}
+export interface Reporter {
+    readonly userId: string;
+    readonly name: string;
+    readonly email: string;
+    /** "" for the 1:1 chat, the conversation id of a group. */
+    readonly scope: string;
+    /** The conversation, for its log lines. */
+    readonly conversationId: string;
+}
+/** The worker's own recent log lines of one chat (ids and levels only), newest last. */
+export interface LogTail {
+    tail(userId: string, conversationId: string): readonly string[];
+}
+export interface FeedbackServiceDeps {
+    readonly reports: FeedbackRepository;
+    readonly links: Pick<LinkRepository, "clawUserIdOf">;
+    readonly sessions: Pick<ClawSessionsPort, "events" | "stream" | "turn">;
+    readonly sink: FeedbackSink | undefined;
+    readonly clock: Clock;
+    readonly log: Logger;
+    readonly mask: Mask;
+    readonly turnText: TurnText;
+    readonly wording: IssueWording;
+    readonly publicBaseUrl: string;
+    readonly worker: WorkerInfo;
+    readonly logs?: LogTail;
+}
+export interface ReportResult {
+    readonly kind: ReportDeliveryKind;
+    readonly number?: number;
+    readonly url?: string;
+    readonly sessionId: string;
+    /** The newest turn of the session: what "my last question and answer" means. */
+    readonly lastTurnId: string;
+}
+export type OfferOutcome = "invalid" | "declined" | "added" | "empty" | "retry";
+export declare class FeedbackService {
+    private readonly deps;
+    readonly delivery: FeedbackDelivery;
+    private readonly history;
+    constructor(deps: FeedbackServiceDeps);
+    get configured(): boolean;
+    /** Record the report, then try to deliver it: the record comes first, so nothing is lost on a failure. */
+    report(who: Reporter, text: string, key: string | undefined, sessionId: string | undefined): Promise<ReportResult>;
+    /** The scene of this chat. Whatever cannot be read is said so in it, and the report goes ahead without it. */
+    collect(who: Reporter, key: string | undefined, sessionId: string | undefined): Promise<Scene>;
+    private readTurns;
+    /** The Yes/No offer for a report that reached the sink, when there is a turn to include; else undefined. */
+    makeOffer(userId: string, result: ReportResult): FeedbackOfferView | undefined;
+    /** The Report a problem button under a message of `userId`'s that went wrong (in a group only they can use it). */
+    reportView(userId: string, scope: string): FeedbackReportView;
+    /** A press on Yes or No under the offer; the offer is read from the store, never from the card. */
+    answerOffer(userId: string, key: string, offerId: string, include: boolean): Promise<[OfferOutcome, number]>;
+    private addExchange;
+}

package/dist/types/feedback/thumbs.d.ts

@@ -0,0 +1,59 @@
+import type { ClawAssistantPort } from "../ports/claw/assistant.js";
+import type { ClawSessionsPort } from "../ports/claw/sessions.js";
+import type { Logger } from "../ports/logger.js";
+import type { ClickHandler, RouteBase, VoteHandler } from "../ports/routing.js";
+import type { SessionRepository } from "../ports/store/sessions.js";
+import { type InboundVote, type OutMessage, type UserRef } from "../ports/surface.js";
+import type { Mask } from "./issue-text.js";
+import type { FeedbackReporting } from "./reporting.js";
+/**
+ * The worker's own thumbs under a final answer, for a client whose thumbs never reach it (Python render.py
+ * `thumbs_card`): the turn engine's `TurnCards.thumbs()`, sent as it is. Its fallback text is the card's question.
+ */
+export declare function thumbsMessage(): OutMessage;
+/** The comment a vote carries, clipped (Claw takes up to 8192). */
+export declare const VOTE_REASON_MAX = 2000;
+export type Reaction = "like" | "dislike";
+export interface ThumbsDeps {
+    readonly reporting: FeedbackReporting;
+    readonly sessions: Pick<SessionRepository, "getSession">;
+    readonly claw: {
+        readonly sessions: Pick<ClawSessionsPort, "vote">;
+        readonly assistant: Pick<ClawAssistantPort, "session">;
+    };
+    readonly credential: (sender: UserRef) => Promise<string | undefined>;
+    /** A 1:1 chat that talks to the person's assistant (its answers are in the assistant's session). */
+    readonly assistantOn: (userId: string) => boolean;
+    /** SHA-256 of a text, as lowercase hex (the runtime's crypto). */
+    readonly sha256Hex: (text: string) => string;
+    readonly mask: Mask;
+    readonly log: Logger;
+}
+/** The key a thumb is stored under in Claw: `teams:<message id>`, hashed when Claw would refuse it as it is. */
+export declare function voteMessageId(sha256Hex: (text: string) => string, messageId: string): string | undefined;
+export declare class FeedbackThumbs {
+    private readonly deps;
+    private readonly counts;
+    private readonly background;
+    constructor(deps: ThumbsDeps);
+    /** The bot's own thumbs card and the comment card a thumbs-down turns it into. */
+    readonly clicks: ClickHandler;
+    /** The thumbs counted since start. */
+    get counted(): Readonly<Record<Reaction, number>>;
+    /** Resolves when every vote and report started so far has finished (for an orderly stop, and for tests). */
+    settled(): Promise<void>;
+    /** The channel's own thumbs, as the router hands them on (Python agent.py: an invoke `thumb_of` reads). */
+    readonly votes: VoteHandler;
+    /** The channel's own thumbs: the person has written their comment in the channel's form. */
+    onVote(route: RouteBase, vote: InboundVote): void;
+    private click;
+    /** Send or Skip under a thumbs-down: filed with what was typed (Skip: without), the card ends as a note. */
+    private noteClick;
+    private count;
+    private track;
+    /** The vote, in the background, never said to the person: one that is not recorded is logged with why. */
+    private vote;
+    private voteInClaw;
+    /** A thumbs-down is filed like /feedback, in the background. */
+    private fileThumb;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * The views of feedback, as core knows them (a channel renders each one; Teams: `teams/src/views/feedback/`). They carry
+ * ids only: whose a button is, and which issue or turn it means, is looked up in the store when it is pressed.
+ */
+/** Thumbs up and down under a final answer, where the channel's own thumbs do not reach the worker (Teams mobile). */
+export type ThumbsView = Readonly<Record<string, never>>;
+/** What a thumbs-down on `ThumbsView` turns into: an optional comment, Send or Skip. */
+export type ThumbCommentView = Readonly<Record<string, never>>;
+/** "Report a problem" under a message that went wrong. In a group only the asker may use it, and the card says so. */
+export interface FeedbackReportView {
+    readonly promptId: string;
+    readonly group: boolean;
+}
+/** Yes or No: add the reporter's last question and answer to the issue. */
+export interface FeedbackOfferView {
+    readonly offerId: string;
+    readonly issueNumber: number;
+}
+/** The offer after a Yes that could not be carried out: a note saying so, with Yes and No again. */
+export interface FeedbackOfferRetryView extends FeedbackOfferView {
+    readonly note: string;
+}
+declare module "../ports/surface.js" {
+    interface ViewMap {
+        thumbs: ThumbsView;
+        thumbComment: ThumbCommentView;
+        feedbackReport: FeedbackReportView;
+        feedbackOffer: FeedbackOfferView;
+        feedbackOfferRetry: FeedbackOfferRetryView;
+    }
+}
+/** The longest comment a thumbs-down card takes (the card's own limit; the handler clips again). */
+export declare const THUMB_COMMENT_MAX = 1000;
+/** The question the offer asks. */
+export declare function offerTitle(issueNumber: number): string;

package/dist/types/guardrails/correlation.d.ts

@@ -0,0 +1,8 @@
+/** One part of an operation's correlation id: an id, a number, a flag or nothing. */
+export type CorrelationPart = string | number | boolean | null | undefined;
+/**
+ * The id that ties the records of one operation together, derived from what every step of it knows (a Claw session
+ * and an approval id; a session, a repository and a pull request), so that nothing has to be stored to carry it:
+ * 32 hex characters.
+ */
+export declare function correlationId(...parts: CorrelationPart[]): string;

package/dist/types/guardrails/guardrails.d.ts

@@ -0,0 +1,49 @@
+import type { Limit } from "../config/settings.js";
+import type { Lang } from "../locales/lang.js";
+import type { SecurityEventName } from "../observability/security-events.js";
+import type { Clock } from "../ports/clock.js";
+import { type SensitiveOperation } from "./operations.js";
+/** Ids of what an audit record is about (a session, a repository, a pull request); never text a person wrote. */
+export type AuditFields = Readonly<Record<string, unknown>>;
+/** Logs one security event (the observability module's `securityEvent`, bound to the worker's logger and metrics). */
+export type AuditSink = (event: SecurityEventName, fields: AuditFields) => void;
+/** An operation a limit refused, and when it can be done again. */
+export declare class Refused {
+    readonly operation: SensitiveOperation;
+    readonly limit: Limit;
+    readonly retryAfterSeconds: number;
+    constructor(operation: SensitiveOperation, limit: Limit, retryAfterSeconds: number);
+    /** The sentence the person is told: what was refused, the limit, and when it can be done again. */
+    text(lang?: Lang): string;
+}
+/**
+ * The per-person limits of the operations that act with someone's authority: a sliding window of how many times one
+ * person did each. Past it the operation is refused, with a `rate_limited` security event. Only the operation that adds
+ * authority is limited (approving, confirming, starting a review, switching to a mode that does not ask). The counts
+ * live in memory (one replica; a restart only ever lets a person do more, never less). One per worker.
+ */
+export declare class Guardrails {
+    private readonly clock;
+    private readonly audit;
+    readonly limits: ReadonlyMap<SensitiveOperation, Limit>;
+    /** `person\u001foperation` -> when it was done and the ticket it was taken with, oldest first */
+    private readonly done;
+    constructor(clock: Clock, audit: AuditSink, limits?: ReadonlyMap<string, Limit>);
+    private now;
+    /** The operation's limit; an operation that is not one refuses (Python's KeyError), never a property of Object.prototype. */
+    private limitOf;
+    /**
+     * Counts one `operation` by `person` and returns null, or, at the limit, counts nothing, logs a `rate_limited`
+     * security event (with `fields`: ids of what was refused) and returns the refusal. `ticket` names this count, for
+     * `giveBack` to undo exactly it.
+     */
+    take(person: string, operation: SensitiveOperation, ticket?: object, fields?: AuditFields): Refused | null;
+    /**
+     * Undoes the `take` made with `ticket`: the operation was not done after all, so it must not use up the person's
+     * allowance. Exactly that count goes, never another one, and only once. A take without a ticket is never given back.
+     */
+    giveBack(person: string, operation: SensitiveOperation, ticket: object | undefined): void;
+    private forget;
+    /** How many (person, operation) the guardrails remember. */
+    get remembered(): number;
+}

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

@@ -0,0 +1,4 @@
+/** Guardrails for the operations that act with someone's authority: per-person limits and audit ids (guardrails.py). */
+export * from "./correlation.js";
+export * from "./guardrails.js";
+export * from "./operations.js";

package/dist/types/guardrails/operations.d.ts

@@ -0,0 +1,22 @@
+import type { Limit } from "../config/settings.js";
+/**
+ * The operations that act with someone's authority and are limited per person; the keys are the `operation`
+ * category of the security events.
+ */
+export declare const SENSITIVE_OPERATIONS: {
+    readonly pr_review: "start a review of a pull request for a colleague (each pull request), or post a held review with one's own GitHub account";
+    readonly pr_merge: "confirm a merge that Claw holds for the person whose GitHub account it uses";
+    readonly approval: "approve a tool call held for approval: a Claw session's approval card, or a remote agent's permission card";
+    readonly remote_agent: string;
+};
+export type SensitiveOperation = keyof typeof SENSITIVE_OPERATIONS;
+export declare const SENSITIVE_OPERATION_NAMES: SensitiveOperation[];
+/** The defaults, per person: a busy coding agent asks for many approvals, a person merges a few pull requests an hour. */
+export declare const DEFAULT_LIMITS: Readonly<Record<SensitiveOperation, Limit>>;
+/** TEAMS_LIMIT_PR_MERGE=20/3600; 0 turns that limit off. */
+export declare const ENV_PREFIX = "TEAMS_LIMIT_";
+/**
+ * The limits from the environment: `TEAMS_LIMIT_<OPERATION>` is `COUNT/SECONDS` (`20/3600`), or `0` to turn that
+ * limit off. Unset takes the default. Anything else throws (the worker stops at start: a typo must not lift a limit).
+ */
+export declare function parseLimits(env: (name: string) => string): Map<SensitiveOperation, Limit>;

package/dist/types/guardrails/sha256.d.ts

@@ -0,0 +1 @@
+export declare function sha256Hex(text: string): string;

package/dist/types/inbound-text/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The texts the model is sent for an inbound message, built from core's inbound types alone: the quote block, the
+ * text with the addresses behind its links, and the text with its mentions marked.
+ */
+export * from "./marked-text.js";
+export * from "./quote-block.js";
+export * from "./redact.js";
+export * from "./when.js";
+export * from "./with-links.js";

package/dist/types/inbound-text/marked-text.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The text of a group message with each person it @mentions replaced by a marker ⟦i⟧ (the Python worker's
+ * `activity.marked_text`), so a reader of the text (a review request: "请 ⟦0⟧ 帮我 review") can tell a person who was
+ * @mentioned from a name that was only typed; mention i is the i-th of the list returned. The addresses behind the
+ * links are added as `withLinks` adds them.
+ *
+ * Input is channel-neutral: the message's text (the bot's own mention already removed by the channel adapter) and its
+ * mentions, each replaced where it stands (`offset`), so a name typed before the same person's mention stays a name.
+ */
+import type { InboundLink, InboundMention } from "../ports/surface.js";
+import { type WithLinksOptions } from "./with-links.js";
+export interface MarkedText {
+    readonly text: string;
+    /** The mentions that were found in the text, in marker order. */
+    readonly mentions: readonly InboundMention[];
+}
+export interface MarkedTextOptions extends WithLinksOptions {
+    readonly links?: readonly InboundLink[];
+}
+export declare function markedText(text: string, mentions: readonly InboundMention[], options?: MarkedTextOptions): MarkedText;

package/dist/types/inbound-text/quote-block.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The message(s) a person quoted, as text for the model (the Python worker's `activity.quote_block` and `with_quote`).
+ * Each quote is a line that says it is a quote and who wrote it ("Quoted your earlier reply" when that was the bot),
+ * then the quoted text with every line after "> ", so nothing a quote says can pass for a line of its own. In a group
+ * the author's name and the text are masked as an outbound message is; all the quotes of a message share one budget of
+ * QUOTE_CHARS characters, cut after the mask (a cut cannot leave half a credential).
+ */
+import { type Logger } from "../ports/logger.js";
+import type { InboundQuote } from "../ports/surface.js";
+import { type Redact } from "./redact.js";
+/** The most quoted text, over all the quotes of one message, that is sent on (code points). */
+export declare const QUOTE_CHARS = 4000;
+/** The most quoted messages that are shown. */
+export declare const QUOTE_COUNT = 5;
+/** The longest author name shown. */
+export declare const NAME_CHARS = 80;
+export interface QuoteBlockOptions {
+    /** A group conversation: names and texts are masked. */
+    readonly group?: boolean;
+    readonly redact?: Redact;
+    readonly logger?: Logger;
+}
+/** `activity.quote_block`: the quotes as text for the model, "" when there are none. */
+export declare function quoteBlock(quotes: readonly InboundQuote[], options?: QuoteBlockOptions): string;
+/** `activity.with_quote`: what the model is sent, the quote (`quoteBlock`) before what the person wrote. */
+export declare function withQuote(text: string, quote: string): string;

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

@@ -0,0 +1,8 @@
+/**
+ * The masking the inbound texts apply in a group conversation (credential-shaped values: the Python worker's
+ * `redact.redact_text(...)[0]`), passed in by the caller. The texts here do not own a masking rule of their own.
+ */
+/** Masks credential-shaped values in `text`. */
+export type Redact = (text: string) => string;
+/** No masking: the default where a caller passes none (a 1:1 conversation needs none). */
+export declare const noRedact: Redact;

package/dist/types/inbound-text/when.d.ts

@@ -0,0 +1,2 @@
+/** `activity._when(raw)`: the UTC minute `raw` names, or "". */
+export declare function whenOf(raw: string): string;

package/dist/types/inbound-text/with-links.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A message's text with the address behind each of its links: what is sent on to the model, and what a review request
+ * reads (the Python worker's `activity.with_links` / `_with_links`). A link shown as other words ("fix the plugin
+ * check" over a pull request's address) gets its address right after those words; a link whose words are not in the
+ * text gets a line of its own. The commands are never read from this text, only from the words alone.
+ */
+import type { InboundLink } from "../ports/surface.js";
+import { type Redact } from "./redact.js";
+export interface WithLinksOptions {
+    /** A group conversation: every member sees what is sent on, so a credential in an address is masked. */
+    readonly group?: boolean;
+    readonly redact?: Redact;
+}
+/**
+ * `text` with the address of every link it does not already carry: after the first place the link's words stand that
+ * no earlier link took, or on a line of its own (`_with_links`). Places are looked up in the original text only.
+ */
+export declare function insertLinks(text: string, links: readonly InboundLink[]): string;
+/** `activity.with_links(text, activity)`: `insertLinks`, the addresses masked in a group. */
+export declare function withLinks(text: string, links: readonly InboundLink[], options?: WithLinksOptions): string;

package/dist/types/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @primusclaw/personal-agent: the channel-neutral core of the personal agent.
+ *
+ * Layers (enforced by .dependency-cruiser.cjs and test/core-is-channel-neutral.test.ts): this package imports nothing
+ * but itself, zod and the Claw wire contract (through ./protocol.ts). Everything else reaches it through a port
+ * (`ports/`) or a plugin (`plugins/`), implemented by the runtime package, a channel package or a deployment.
+ */
+export * from "./errors.js";
+export * from "./brief/index.js";
+export * from "./feedback/index.js";
+export * from "./json.js";
+export * from "./own.js";
+export * from "./guardrails/index.js";
+export * from "./limits/index.js";
+export * from "./review-text/index.js";
+export { INTENT_PROMPT, MODE_PROMPT } from "./locales/review-github.js";
+export * from "./typed-answer/index.js";
+export * from "./understanding/index.js";
+export * from "./locales/index.js";
+export * from "./observe/index.js";
+export * from "./plugins/index.js";
+export * from "./ports/crypto.js";
+export * from "./ports/index.js";
+export * from "./ports/store/index.js";
+export * from "./protocol.js";
+export * from "./result.js";
+export * from "./text/py-regex.js";
+export * from "./text/py-text.js";
+export * from "./validate.js";
+export * from "./claw/credential.js";
+export * from "./claw/errors.js";
+export * from "./claw/model.js";
+export * from "./claw/remote.js";
+export * from "./config/settings.js";
+export * from "./observability/security-events.js";
+export * as turn from "./turn/index.js";
+export { fetchChanges } from "./turn/changes.js";
+export * from "./note/note.js";
+export * from "./branding.js";
+export * from "./claw/message-text.js";
+export * from "./claw/requester-view.js";
+export * from "./claw/service-refusal.js";
+export * from "./claw/sse.js";
+export * from "./claw/started-review.js";
+export * from "./claw/work-item.js";
+export * from "./locales/claw.js";
+export * from "./public-error/index.js";
+export * from "./security/redact.js";
+export * from "./observability/ip-address.js";
+export * from "./observability/security-fields.js";
+export * from "./observability/security-log.js";
+export * from "./claw/py-value.js";
+export * from "./observability/metrics-catalog.js";
+export * from "./language/detect.js";
+export * from "./inbound-text/index.js";
+export * from "./routing/index.js";
+export * from "./approvals/index.js";
+export * from "./assistant/index.js";
+export * from "./assistant/work-items.js";
+export type * from "./assistant/views.js";
+export * from "./direct-chat/index.js";
+export * from "./proactive/index.js";
+export * from "./proactive/views.js";
+export * from "./subscriptions/index.js";
+export * from "./review/index.js";
+export * as remoteDomain from "./remote/index.js";
+export * as remoteView from "./remote-view/index.js";
+export { RemoteAgents } from "./remote/remote-agents.js";
+export type { RemoteContext, RemoteErrors, RemoteGuard, RemoteSettings } from "./remote/context.js";
+export { ConnectorSetup, setupFrom } from "./remote/connector/setup.js";
+export { CredentialUnavailable as FollowCredentialUnavailable } from "./remote/follow/follower.js";
+export type { FollowReach } from "./remote/follow/speaker.js";
+export { DEFAULT_TIMINGS as REMOTE_FOLLOW_TIMINGS, WATCH_TIMINGS as REMOTE_WATCH_TIMINGS, } from "./remote/follow/timings.js";

package/dist/types/json.d.ts

@@ -0,0 +1,5 @@
+/** A value that survives `JSON.stringify` / `JSON.parse` unchanged. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | JsonObject;
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}

package/dist/types/language/detect.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Which language a person is answered in (teams_agent/approval_view.py: has_cjk, written_lang, pick_lang, answer_lang).
+ *
+ * The client's locale is passed in, never read from ambient state: the caller that handles an inbound message knows it.
+ */
+import type { Lang } from "../locales/lang.js";
+export declare function hasCjk(text: unknown): boolean;
+/**
+ * The language a message is written in, when it says so: "zh" with Chinese in it, "en" for a sentence in English (three words or
+ * more, one of them glue, a lower-case -ed/-ing form, or the first a verb of a request); otherwise undefined.
+ */
+export declare function writtenLang(text: unknown): Lang | undefined;
+/** Chinese when the first text that has any non-space character has Chinese in it, else English. */
+export declare function pickLang(...texts: unknown[]): Lang;
+/**
+ * The language a person is answered in: `said` (the conversation's chosen or learnt language) when set; else the locale of the
+ * Teams client the message being handled came from; else that of `texts` (`pickLang`).
+ */
+export declare function answerLang(said: string, clientLocale: string, ...texts: unknown[]): Lang;
+/** Python's `str(x or "")`: the text of a value, "" for anything falsy. */
+export declare function asText(value: unknown): string;

package/dist/types/limits/inbound-stats.d.ts

@@ -0,0 +1,42 @@
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import { type MetricsPort } from "../ports/metrics.js";
+/** One `inbound_stats` line per this many seconds (when anything happened). */
+export declare const STATS_INTERVAL_SECONDS = 60;
+/** What one `inbound_stats` line says. */
+export interface InboundSnapshot {
+    readonly event: "inbound_stats";
+    readonly interval_seconds: number;
+    readonly handled: number;
+    readonly failed: number;
+    readonly lag_max_ms: number;
+    readonly lag_avg_ms: number;
+    readonly handle_max_ms: number;
+    readonly handle_avg_ms: number;
+    readonly rate_limited: number;
+    readonly concurrency_limited: number;
+}
+/**
+ * Counters for the inbound path, logged as one `inbound_stats` line per interval in which anything happened: messages
+ * handled, the longest and average time a message waited in the queue (lag), the longest and average handling time,
+ * failures, and refusals by a limit. Each message and refusal is also counted in `metrics`, for /metrics.
+ */
+export declare class InboundStats {
+    private readonly clock;
+    private readonly logger;
+    private readonly metrics;
+    private readonly intervalSeconds;
+    private counts;
+    private since;
+    constructor(clock: Clock, logger: Logger, metrics?: MetricsPort, intervalSeconds?: number);
+    private now;
+    /** Messages handled since the last line. */
+    get handled(): number;
+    processed(lagMs: number | null, handleMs: number, ok: boolean): void;
+    limited(reason: string): void;
+    /** Files a person sent that did not reach Claw, counted for /metrics only. */
+    filesDropped(path: string, count: number): void;
+    snapshot(): InboundSnapshot;
+    flushDue(): void;
+    flush(): void;
+}

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

@@ -0,0 +1,5 @@
+/** Per-person limits on what one person can make the worker do, and the inbound path's counters (limits.py). */
+export * from "./inbound-stats.js";
+export * from "./rate-limiter.js";
+export * from "./user-limits.js";
+export * from "./wait-words.js";

package/dist/types/limits/rate-limiter.d.ts

@@ -0,0 +1,32 @@
+import type { Clock } from "../ports/clock.js";
+/** Checks between two passes that forget idle people. */
+export declare const PRUNE_EVERY = 1000;
+/** The answer for one message. */
+export interface Verdict {
+    readonly allowed: boolean;
+    /** Refused, and this is the first refusal of the burst: tell the person (once). */
+    readonly notify: boolean;
+    /** Refused: seconds until one message more fits in the window. */
+    readonly retryAfterSeconds: number;
+}
+/**
+ * A sliding window per person: at most `limit` accepted messages in any `windowSeconds`. Refused messages are not
+ * counted, so a person who keeps sending while refused is let through again as soon as the oldest accepted message
+ * leaves the window. A person is told once per burst, not once per dropped message.
+ */
+export declare class MessageRateLimiter {
+    readonly limit: number;
+    readonly windowSeconds: number;
+    private readonly clock;
+    private readonly hits;
+    /** person -> the end of the burst they were told about */
+    private readonly toldUntil;
+    private checks;
+    constructor(limit: number, windowSeconds: number, clock: Clock);
+    private now;
+    check(user: string): Verdict;
+    /** Forget people with nothing in the window (memory stays bounded by the people active in the last window). */
+    prune(): void;
+    /** How many people the limiter remembers. */
+    get remembered(): number;
+}

package/dist/types/limits/user-limits.d.ts

@@ -0,0 +1,18 @@
+import type { UserLimits } from "../config/settings.js";
+/** TEAMS_USER_MESSAGE_LIMIT: messages per window and person. */
+export declare const DEFAULT_MESSAGE_LIMIT = 20;
+/** TEAMS_USER_MESSAGE_WINDOW_SECONDS. */
+export declare const DEFAULT_MESSAGE_WINDOW_SECONDS = 60;
+/**
+ * TEAMS_USER_MAX_CONCURRENT_TASKS. A review request starts up to 10 pull requests at once, each a task; the default
+ * leaves room for that beside the person's 1:1 chat and a group.
+ */
+export declare const DEFAULT_MAX_CONCURRENT_TASKS = 12;
+/**
+ * A message to the assistant may start a work item, which shows on the board only once the assistant decided to make
+ * one: until then (or for this long, when it starts none) it holds one task slot.
+ */
+export declare const ASSISTANT_PENDING_SECONDS = 90;
+export declare const DEFAULT_USER_LIMITS: UserLimits;
+/** `limits`, or a RangeError naming the first field that is not a positive whole number (they cannot be turned off). */
+export declare function userLimits(limits?: UserLimits): UserLimits;

package/dist/types/limits/wait-words.d.ts

@@ -0,0 +1,3 @@
+import type { Lang } from "../locales/lang.js";
+/** How long to wait, in words: whole seconds (at least 1) under two minutes, else minutes rounded up. */
+export declare function waitWords(seconds: number, lang?: Lang): string;

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

@@ -0,0 +1,49 @@
+/** `/whoami`, `/memory`, `/lang` and the first lines of help. */
+export declare const accountText: import("./catalog.js").Catalog<{
+    connectedTo: (p: {
+        name: string;
+        email: string;
+    }) => string;
+    whoamiFirst: (p: {
+        name: string;
+        email: string;
+    }) => string;
+    whoamiUnknown: string;
+    memoryUnreadable: (p: {
+        page: string;
+    }) => string;
+    memoryUnavailable: string;
+    memoryOff: (p: {
+        page: string;
+    }) => string;
+    nothingRemembered: string;
+    memoryOn: (p: {
+        lines: string;
+        page: string;
+    }) => string;
+    memoryUsage: string;
+    memoryNotChanged: (p: {
+        page: string;
+    }) => string;
+    memoryTurnedOn: (p: {
+        page: string;
+    }) => string;
+    memoryTurnedOff: (p: {
+        page: string;
+    }) => string;
+    langChosen: (p: {
+        lang: string;
+    }) => "好的，以后用中文回复你。发 `/lang auto` 改回按你写的话自动选。" | "OK, I answer you in English from now on. Send `/lang auto` to have it follow what you write again.";
+    langUsage: string;
+    langWhySet: string;
+    langWhyWritten: string;
+    langWhyClient: string;
+    langIs: (p: {
+        name: string;
+        why: string;
+    }) => string;
+}>;
+/** The languages' names: [Chinese, English]. */
+export declare const LANG_NAMES: Readonly<Record<"zh" | "en", readonly [string, string]>>;
+/** `/memory on|off` in the words people use for it. */
+export declare const MEMORY_SWITCH: Readonly<Record<string, boolean>>;