@primusclaw/personal-agent 0.0.0-stage → 0.1.1

package/dist/types/commands/parse.d.ts

@@ -0,0 +1,33 @@
+import { type Command } from "./names.js";
+/** The command name if `text` is exactly a known command, else null. */
+export declare function parseCommand(text: string): Command | null;
+/** The argument text of `/name ARGS` ("" when there is none), or null when `text` is not that command. */
+export declare function commandArgs(text: string, name: string): string | null;
+/**
+ * What Teams' commands menu inserts. Choosing an entry puts the entry's TITLE in the compose box with no slash (`help`,
+ * `agent detach`), and a person who types a menu word without a slash means the same: a message that is exactly one of these words
+ * is the command, in every state of the chat. `sessions` and `detach` are the remote agent's (`/agent sessions`, `/agent detach`),
+ * not Claw's own `/sessions`, which a person still types with its slash. Nothing but an exact match counts: `help me` is a sentence.
+ */
+export declare const MENU_COMMANDS: Readonly<Record<string, string>>;
+/** The entries of the group chat's own menu. */
+export declare const GROUP_MENU_COMMANDS: readonly ["help", "new", "stop", "whoami", "feedback"];
+/**
+ * `text` as the command it is when it is exactly a word of the commands menu (case and spacing do not matter), `link CODE` with a
+ * code of the console's shape as `/link CODE`, and `text` itself otherwise. `group`: a group chat reads only its own menu's words.
+ */
+export declare function menuCommand(text: string, group?: boolean): string;
+/** The code of a `/link CODE` message, else null. */
+export declare function parseLinkCode(text: string): string | null;
+/** Whether `text` is a /timezone message, and its argument: null for none, "" for more than one word. */
+export declare function parseTimezone(text: string): {
+    isTimezone: boolean;
+    arg: string | null;
+};
+export declare const MAX_PAUSE_SECONDS: number;
+/** '8:30' to '08:30'; null unless it is a real 24-hour time. */
+export declare function parseClock(text: string): string | null;
+/** '22:00-08:00' to ['22:00', '08:00']; null when malformed or empty (start equals end). */
+export declare function parseQuietWindow(text: string): readonly [string, string] | null;
+/** '2h', '30m', '1d' to seconds, at most 30 days; null when malformed. */
+export declare function parseDurationSeconds(text: string): number | null;

package/dist/types/commands/repo.d.ts

@@ -0,0 +1,17 @@
+export declare const REPO_HOST = "https://github.com";
+export interface RepoPick {
+    /** "owner/name", as typed. */
+    readonly repo: string;
+    /** "" is the remote's default branch. */
+    readonly branch: string;
+}
+export declare function repoUrl(pick: RepoPick): string;
+export declare function repoLabel(pick: RepoPick): string;
+export declare function validRepo(repo: string): boolean;
+/**
+ * A name git accepts for a branch (`git check-ref-format`, narrowed to letters, digits and `._/-`): no leading `-` or `/`, no
+ * `..`, no empty (so no leading, trailing or double `/`), dotted or `.lock` component, no trailing `.`. Claw checks it again.
+ */
+export declare function validBranch(branch: string): boolean;
+/** `owner/name` or `owner/name branch` (what follows `/repo`) to a pick; null for anything else. */
+export declare function parseRepo(args: string): RepoPick | null;

package/dist/types/config/settings.d.ts

@@ -0,0 +1,124 @@
+import type { SecretsSourceName } from "../ports/secret-source.js";
+import type { LinkLimits } from "../ports/store/link.js";
+/**
+ * The worker's channel-neutral settings, read once at start (the runtime's `readSettings` from the environment; the
+ * environment variable each field comes from is named beside it). A channel adds its own (the Teams package: outbound
+ * mode, bot token, Service Bus, reply style). Nothing here has a built-in address: a deployment says its own.
+ */
+export interface Settings {
+    /** TEAMS_DB_PATH (default /data/state.db). */
+    readonly dbPath: string;
+    /** TEAMS_ENCRYPTION_KEYS, comma separated Fernet keys: the first encrypts, all decrypt. */
+    readonly encryptionKeys: readonly string[];
+    /** CLAW_API_URL, without a trailing slash. */
+    readonly clawApiUrl: string;
+    /** SAFE_API_URL, without a trailing slash (the platform API; its LLM gateway reads review requests). */
+    readonly safeApiUrl: string;
+    /** PUBLIC_BASE_URL, without a trailing slash: where this deployment is reached. */
+    readonly publicBaseUrl: string;
+    /** PORT (default 8080): the public listener. */
+    readonly listenPort: number;
+    /** METRICS_PORT (default 9090), never PORT. */
+    readonly metricsPort: number;
+    readonly claw: ClawSettings;
+    readonly exchange: ExchangeSettings;
+    readonly models: ModelSettings;
+    readonly githubReview: GithubReviewSettings;
+    readonly assistant: AssistantSettings;
+    /** TEAMS_CLAW_EVENTS_GONE: an event for a person with no chat is answered 410 Gone instead of 200 `dropped`. */
+    readonly clawEventsGone: boolean;
+    /** TEAMS_DIRECT_CHAT and TEAMS_DIRECT_CHAT_USERS (lower-cased; empty with `on` is everybody). */
+    readonly directChat: {
+        readonly enabled: boolean;
+        readonly users: ReadonlySet<string>;
+    };
+    /** TEAMS_ON_BEHALF_USERS: Claw user ids (as written) whose own key may post into their own chat. */
+    readonly onBehalfUsers: ReadonlySet<string>;
+    /** TEAMS_OBSERVE_USERS (lower-cased): who may turn on observing a group chat. */
+    readonly observeUsers: ReadonlySet<string>;
+    /** TEAMS_LIMIT_<OPERATION>: the per-person limits of operations that act with someone's authority. */
+    readonly sensitiveLimits: ReadonlyMap<string, Limit>;
+    /** TEAMS_LINK_MAX_FAILURES_PER_USER (5) / TEAMS_LINK_MAX_FAILURES_GLOBAL (100) / TEAMS_LINK_ATTEMPT_WINDOW_SECONDS (600). */
+    readonly linkLimits: LinkLimits;
+    readonly userLimits: UserLimits;
+    /** SECRETS_SOURCE (env | keyvault). */
+    readonly secretsSource: SecretsSourceName;
+}
+/** How this worker talks to Claw. */
+export interface ClawSettings {
+    /** CLAW_PLUGIN_ID; null creates plain sessions. */
+    readonly pluginId: number | null;
+    /** CLAW_RULE_TOOL_ID: the rule tool whose text rides on every message; null none. */
+    readonly ruleToolId: number | null;
+    /** CLAW_CLIENT_LABEL (default "clawy"): what Claw's audit trail calls this client (`X-Claw-Client`). */
+    readonly clientLabel: string;
+}
+/** Token exchange with the identity service (RFC 8693). */
+export interface ExchangeSettings {
+    /** TEAMS_EXCHANGE_ENABLED. */
+    readonly enabled: boolean;
+    /** TEAMS_EXCHANGE_TOKEN_URL (default PUBLIC_BASE_URL/oauth/token); "" when off. */
+    readonly tokenUrl: string;
+    /** TEAMS_EXCHANGE_CLIENT_ID, required when on. */
+    readonly clientId: string;
+    /** The secret TEAMS_EXCHANGE_CLIENT_SECRET, required when on. */
+    readonly clientSecret: string;
+    /** TEAMS_EXCHANGE_ISSUER (default teams.microsoft.com). */
+    readonly issuer: string;
+    /** TEAMS_EXCHANGE_AUDIENCE (default claw-api). */
+    readonly audience: string;
+    /** TEAMS_EXCHANGE_SCOPE (default claw.api). */
+    readonly scope: string;
+    /** TEAMS_EXCHANGE_BINDING_REQUEST_URL (default PUBLIC_BASE_URL/oauth/binding-requests); "" when off. */
+    readonly bindingRequestUrl: string;
+    /** TEAMS_EXCHANGE_FOR_CHAT: ordinary chats use a bound person's exchanged token instead of their linked key. */
+    readonly forChat: boolean;
+}
+/** The models sessions ask for ("" sends none: Claw's default applies). */
+export interface ModelSettings {
+    /** CLAWY_MODEL. */
+    readonly chat: string;
+    /** CLAWY_FALLBACK_MODEL: a turn refused for want of a model key is run again on it, once ("" no second run). */
+    readonly fallback: string;
+    /** CLAWY_REVIEW_MODEL: a review whose request names none ("" CLAWY_MODEL). */
+    readonly review: string;
+}
+/** Reviewing and merging a pull request for a colleague. */
+export interface GithubReviewSettings {
+    /** TEAMS_GITHUB_REVIEW_ENABLED (needs the exchange). */
+    readonly enabled: boolean;
+    /** TEAMS_GITHUB_REVIEW_OWNERS: the GitHub owners whose pull requests are taken; required when on. */
+    readonly owners: readonly string[];
+    /** TEAMS_REVIEW_INTENT_MODEL (else CLAWY_MODEL) when on; "" requests are read by the rules alone. */
+    readonly intentModel: string;
+    /** TEAMS_GITHUB_CREDENTIAL_URL (default PUBLIC_BASE_URL/oauth/external-credentials) when on. */
+    readonly credentialUrl: string;
+    /** TEAMS_GITHUB_CLIENT_ID: the OAuth client of the device flow (default: the GitHub CLI's public client). */
+    readonly clientId: string;
+}
+/** A person's assistant in Claw. */
+export interface AssistantSettings {
+    /** ASSISTANT_ENABLED. */
+    readonly enabled: boolean;
+    /** ASSISTANT_USERS (lower-cased; empty: everybody). */
+    readonly users: ReadonlySet<string>;
+    /** ASSISTANT_REPLY_WINDOW_SECONDS (default 1800). */
+    readonly replyWindowSeconds: number;
+    /** TEAMS_ASSISTANT_UNDERSTANDING(_USERS): whose every message the assistant understands first (empty: nobody). */
+    readonly understandingUsers: ReadonlySet<string>;
+}
+/** How many in a window; `count` 0: no limit. */
+export interface Limit {
+    readonly count: number;
+    readonly windowSeconds: number;
+}
+/** TEAMS_USER_MESSAGE_LIMIT per TEAMS_USER_MESSAGE_WINDOW_SECONDS, TEAMS_USER_MAX_CONCURRENT_TASKS. */
+export interface UserLimits {
+    readonly messageLimit: number;
+    readonly messageWindowSeconds: number;
+    readonly maxConcurrentTasks: number;
+}
+/** A setting that is missing or malformed: the worker stops at start (a typo must not quietly pick a value). */
+export declare class ConfigError extends Error {
+    readonly name = "ConfigError";
+}

package/dist/types/direct-chat/direct-chat.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The chat itself as the window of an agent session on the person's machine (TEAMS_DIRECT_CHAT, teams_agent/direct_chat.py).
+ *
+ * For the people it is on for, a chat attached to an agent session is a plain conversation with that agent: every message says in
+ * its first line who speaks (`agentHead`, `CLAWY_HEAD`), a line of the agent's that looks like a head is escaped (`guardHeads`),
+ * entering and leaving are one line each, and the way back and forth is a suggested reply. Off (the default) changes nothing.
+ */
+import type { Lang } from "../locales/lang.js";
+/** A suggested reply: (what the button says, what it sends). */
+export type SuggestedReply = readonly [title: string, value: string];
+export declare const CLAWY_HEAD = "\uD83D\uDCAC **Clawy**";
+export declare const NEUTRAL_ICON = "\uD83E\uDD16";
+/** The first line of what an agent writes: its icon, then its name and its machine in bold (`🟠 **Claude Code · dev-pod**`). */
+export declare function agentHead(label: string, host: string): string;
+/** The first line of the second and later messages of one answer: the agent's icon and where it is in the answer. */
+export declare function continuedHead(label: string, n: number, total: number, lang: string): string;
+/** The agent's words with every line that would read as a head escaped (its bold shown as asterisks). */
+export declare function guardHeads(text: string): string;
+/** `text` under `head`, as its own paragraph. */
+export declare function signed(head: string, text: string): string;
+/** The messages of one thing an agent said, each headed: the first with who said it (and `suffix`), the others with where they are. */
+export declare function signedParts(label: string, host: string, parts: readonly string[], lang: string, suffix?: string): string[];
+export declare const OWN_SUFFIX: Readonly<Record<Lang, string>>;
+export declare const TYPED_SUFFIX: Readonly<Record<Lang, string>>;
+export declare const BACK: Readonly<Record<Lang, SuggestedReply>>;
+/** The suggested replies under what the agent said: go on with it, or back to Clawy. */
+export declare function agentReplies(lang: string): SuggestedReply[];
+export declare function backReply(lang: string): SuggestedReply;
+/** The reply that attaches the chat to the agent it last talked to again (`/agent attach MACHINE/AGENT`); undefined when none. */
+export declare function returnReply(label: string, host: string, agentId: string, lang: string): SuggestedReply | undefined;
+export interface EnteredLine {
+    readonly label: string;
+    readonly host: string;
+    readonly cwd: string;
+    readonly mode: string;
+    readonly lang: string;
+    readonly unattended?: boolean;
+    readonly lead?: string;
+}
+/** The one line a chat gets when it attaches to (or switches to) a session. */
+export declare function enteredLine(entered: EnteredLine): string;
+/** The one line a chat gets when it leaves the session: its messages go to Clawy again. */
+export declare function leftLine(lang: string): string;
+/** `/agent mode card|chat` while this is on: the chat is the window, for everybody it is on for. */
+export declare function modeUnifiedLine(lang: string): string;
+/** Where a person's chat is attached, as far as Clawy's own words need it. */
+export interface AttachedState {
+    readonly sessionId: string;
+    readonly agentLabel: string;
+    readonly host: string;
+    readonly agentId: string;
+}
+/** Reads where a person's chat is attached (the remote-agent state; W6 owns it). */
+export interface AttachedStateReader {
+    remoteState(aadId: string): AttachedState | undefined;
+}
+export interface ClawyExtras {
+    readonly head: string;
+    readonly replies: readonly SuggestedReply[];
+}
+/** The switch: off (undefined), on for everybody (empty set) or on for the people listed (lower-case ids). */
+export declare class DirectChat {
+    private readonly users;
+    constructor(on: boolean, users?: Iterable<string>);
+    /** Whether the chat of this person (or a group binding of theirs: the part before '|') is an agent's window when attached. */
+    on(aadId: string): boolean;
+    describe(): string;
+    /**
+     * The head and suggested replies of what Clawy says to this person: attached, `CLAWY_HEAD` and "Back to Clawy"; not attached,
+     * no head and the way back to the agent it last talked to; nothing when this is off for them.
+     */
+    clawyExtras(state: AttachedStateReader, aadId: string, lang: string): ClawyExtras;
+}

package/dist/types/direct-chat/index.d.ts

@@ -0,0 +1,2 @@
+/** What the assembly wires of direct chat. */
+export { DirectChat } from "./direct-chat.js";

package/dist/types/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Errors that are thrown (see `result.ts` for when to throw and when to return a failure).
+ *
+ * A message of a thrown error may end up in a log line; it never carries user text, a token or a response body.
+ * `errorName` is what is logged about an error that came from outside (an exception of a dependency): its type only,
+ * the way the Python worker logged `type(err).__name__`.
+ */
+/** A broken invariant of this package: a bug, never a condition a user or a peer can cause. */
+export declare class InvariantError extends Error {
+    readonly name = "InvariantError";
+}
+/** The kind of an error, safe to log: its constructor's name, or the type of a non-error value that was thrown. */
+export declare function errorName(error: unknown): string;
+/** Exhaustiveness check for a discriminated union: `default: return unreachable(x)`. */
+export declare function unreachable(value: never): never;

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

@@ -0,0 +1,10 @@
+import type { Clock } from "../ports/clock.js";
+/** A step of a report that took longer than it may (Python's `TimeoutError` from `asyncio.timeout`). */
+export declare class DeadlineExceeded extends Error {
+    readonly name = "TimeoutError";
+}
+/**
+ * `work`, given `ms` of `clock`: past that, the returned promise rejects with DeadlineExceeded and `work`'s signal is
+ * aborted, so what it waits on (a stream) stops. The clock's timer is cancelled once `work` settles.
+ */
+export declare function withDeadline<T>(clock: Clock, ms: number, work: (signal: AbortSignal) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,34 @@
+import type { FeedbackSink, IssueRef } from "../plugins/feedback-sink.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 IssueWording } from "./issue-text.js";
+export type ReportDeliveryKind = "filed" | "commented" | "unconfigured" | "error";
+export interface ReportDelivery {
+    readonly kind: ReportDeliveryKind;
+    readonly issue?: IssueRef;
+}
+export interface ReportDeliveryDeps {
+    readonly reports: FeedbackRepository;
+    /** Undefined: no sink is configured, reports are only recorded. */
+    readonly sink: FeedbackSink | undefined;
+    readonly clock: Clock;
+    readonly log: Logger;
+    readonly wording: IssueWording;
+    readonly publicBaseUrl: string;
+}
+export declare class FeedbackDelivery {
+    private readonly deps;
+    private queue;
+    constructor(deps: ReportDeliveryDeps);
+    get configured(): boolean;
+    /** Delivers report `reportId` unless it was already; never throws for a delivery that failed (it is recorded). */
+    deliver(reportId: number): Promise<ReportDelivery>;
+    /** Files the reports whose retry time has come; how many went out. */
+    replayPending(limit?: number): Promise<number>;
+    private deliverNow;
+    private send;
+    /** False when the issue is gone (404, 410): a fresh one is filed instead. */
+    private commentOn;
+    private failed;
+}

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

@@ -0,0 +1,19 @@
+import type { SseEvent } from "../claw/model.js";
+import { type HistoryRow } from "./scene.js";
+/**
+ * A reporter's last question and the answer to it, as the chat showed them: what they chose to add to their issue.
+ * Reading an answer is the turn engine's (`answerOf`: the text a turn's events showed), and so is taking the worker's
+ * own additions off a question (`withoutRule`).
+ */
+export interface TurnText {
+    /** The text the person typed, without what the worker appended to it (the change summary, the reply-style rule). */
+    withoutRule(text: string): string;
+    /** The answer a turn's events showed, as the chat showed it. */
+    answerOf(turnId: string, events: readonly SseEvent[]): string;
+}
+export interface Exchange {
+    readonly question: string;
+    readonly answer: string;
+}
+/** The exchange of the turn `turnId` (else the last turn); undefined when there is neither a question nor an answer. */
+export declare function lastExchange(rows: readonly HistoryRow[], turnId: string, text: TurnText): Exchange | undefined;

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

@@ -0,0 +1,36 @@
+import type { Logger } from "../ports/logger.js";
+import type { ClickHandler, MessageInterceptor, MessageRoute } from "../ports/routing.js";
+import type { FeedbackRepository } from "../ports/store/feedback.js";
+import { type OutMessage } from "../ports/surface.js";
+import type { FeedbackReporting } from "./reporting.js";
+import type { FeedbackService, OfferOutcome } from "./service.js";
+/**
+ * `/feedback [TEXT]` and the question a bare `/feedback` asks, the Report a problem button, and Yes/No under the offer
+ * to add the last question and answer. The thumbs are `thumbs.ts`.
+ */
+export interface FeedbackFlowDeps {
+    readonly reports: FeedbackRepository;
+    readonly reporting: FeedbackReporting;
+    readonly service: FeedbackService;
+    readonly log: Logger;
+}
+export declare class FeedbackFlow {
+    private readonly deps;
+    constructor(deps: FeedbackFlowDeps);
+    /** The interceptor of 1:1 and group chats: before the account check, so an unlinked person can report too. */
+    readonly interceptor: MessageInterceptor;
+    /** Report a problem (both chats) and the offer's Yes/No (1:1, with the person's credential). */
+    readonly clicks: ClickHandler;
+    /** True when the message was feedback: `/feedback [TEXT]`, or the answer to "What went wrong?". */
+    entry(route: MessageRoute): Promise<boolean>;
+    /**
+     * Report a problem: the same question as a bare /feedback. The button is looked up in the store, so a group member
+     * other than the one whose message went wrong cannot use it. Every outcome replaces the clicked card.
+     */
+    private reportClick;
+    /** Yes or No under the offer: read from the store (its owner, issue and turn), the conversation with the clicker's key. */
+    private offerClick;
+}
+export declare function offerOutcomeText(outcome: Exclude<OfferOutcome, "retry">, issueNumber: number): string;
+/** The Report a problem card, as a message. */
+export declare function reportMessage(promptId: string, group: boolean): OutMessage;

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

@@ -0,0 +1,16 @@
+import type { DailyBrief } from "../brief/brief.js";
+import type { Observer } from "../observe/observer.js";
+import type { RouteHandlers } from "../ports/routing.js";
+import type { FeedbackFlow } from "./flow.js";
+import type { FeedbackThumbs } from "./thumbs.js";
+/**
+ * What feedback, observation and the daily brief give the router, in the Python worker's order: in a 1:1 chat the
+ * feedback answer is read before the account check; in a group `/observe` is read first, then the feedback answer; the
+ * buttons of each card by their kind; the channel's own thumbs as a vote (`FeedbackThumbs.onVote`).
+ */
+export declare function w8RouteHandlers(parts: {
+    readonly flow: FeedbackFlow;
+    readonly thumbs: FeedbackThumbs;
+    readonly observer: Observer;
+    readonly brief: DailyBrief;
+}): RouteHandlers;

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

@@ -0,0 +1,20 @@
+import type { ClawSessionsPort } from "../ports/claw/sessions.js";
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { HistoryRow } from "./scene.js";
+/**
+ * The last events of a session, read with the person's own key, for a report: the scene's last turns, and the last
+ * exchange a reporter chose to add. Never the whole history: an assistant session runs for weeks (one reached 33,196
+ * events, 28.6 MB), so the replay asks for the tail alone and refuses a larger reply unread (an older Claw ignores
+ * `tail`); when the replay cannot be used, the stream's history is read event by event and only its tail is kept.
+ */
+export declare const HISTORY_TAIL = 200;
+export declare const HISTORY_MAX_BYTES: number;
+/** Why a session could not be read, as a report's scene says it: never a body or a message. */
+export declare function whyNotRead(err: unknown): string;
+export interface HistoryReader {
+    readonly sessions: Pick<ClawSessionsPort, "events" | "stream">;
+    readonly clock: Clock;
+    readonly log: Logger;
+}
+export declare function readHistory(reader: HistoryReader, key: string, sessionId: string): Promise<HistoryRow[]>;

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

@@ -0,0 +1,16 @@
+/**
+ * The shapes a value must have to be echoed into a report. Each pattern ends like Python's `re.match(...$)`: a single
+ * trailing newline is allowed, as the Python worker allowed it.
+ */
+/** What may be echoed from an event or a log field: an id, a status, a tool name. */
+export declare const TOKEN: RegExp;
+/** An image tag. */
+export declare const TAG: RegExp;
+/** `owner/name` of the repository issues go to. */
+export declare const REPO: RegExp;
+/** A plain email address (nothing else may be written into the markdown). */
+export declare const EMAIL: RegExp;
+/** An image tag as a report shows it: the tag, or "unknown" when it is not one (Python's `_env_tag` after its strip). */
+export declare function tagOf(value: string): string;
+/** A value that may be echoed: a short identifier-shaped string, or an integer; undefined for anything else. */
+export declare function tokenOf(value: unknown): string | undefined;

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

@@ -0,0 +1,16 @@
+export * from "./identifiers.js";
+export * from "./issue-text.js";
+export * from "./markdown.js";
+export * from "./scene.js";
+export { FEEDBACK_TEXT, feedbackText } from "../locales/feedback.js";
+export * from "./deadline.js";
+export * from "./delivery.js";
+export * from "./exchange.js";
+export * from "./flow.js";
+export * from "./handlers.js";
+export * from "./history.js";
+export * from "./log-text.js";
+export * from "./reporting.js";
+export * from "./service.js";
+export * from "./thumbs.js";
+export * from "./views.js";

package/dist/types/feedback/iso-time.d.ts

@@ -0,0 +1,2 @@
+/** Seconds since the epoch of an ISO 8601 text as Python's `fromisoformat` reads it, or undefined where it refuses. */
+export declare function isoSeconds(value: string): number | undefined;

package/dist/types/feedback/issue-text.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The words of an issue and its comments: the title, who reported it, the body, the comment of a second report in the
+ * same session, and the comment with the conversation the reporter chose to add. Everything a person wrote is masked
+ * (`Mask`), bounded, and kept from forming markdown that pings, links or forges the retry marker.
+ */
+/** Credential shapes in a text replaced by a placeholder (the runtime's redaction). */
+export type Mask = (text: string) => string;
+export declare const FEEDBACK_LABEL = "clawy-feedback";
+export declare const LABEL_COLOR = "d93f0b";
+export declare const LABEL_DESCRIPTION = "Reported by a user from Teams through Clawy";
+export declare const MAX_TEXT_CHARS = 4000;
+/** How the deployment names itself and where its users talk to it. */
+export interface IssueWording {
+    /** The bot's display name ("Clawy"). */
+    readonly botName: string;
+    /** The chat channel ("Teams"). */
+    readonly channelName: string;
+}
+/** A stored report, as far as its issue text needs it. */
+export interface ReportText {
+    readonly id: number;
+    /** Seconds since the epoch. */
+    readonly createdAt: number;
+    readonly text: string;
+    /** The scene, as markdown (`sceneMarkdown`). */
+    readonly scene: string;
+    readonly reporterName: string;
+    readonly reporterEmail: string;
+    readonly sessionId: string;
+}
+/** One line of printable text, at most `limit` characters (an ellipsis marks a cut). */
+export declare function plainLine(value: string, limit: number): string;
+export declare function reporterName(value: string): string;
+/** The email when it is a plain address, else "": it is written into markdown, so nothing else may pass. */
+export declare function reporterEmail(value: string): string;
+/** The first line of every issue and comment: who reported it, escaped so it cannot format, link, ping or forge. */
+export declare function reporterLine(name: string, email: string): string;
+/** `[<bot> feedback] <what went wrong> — <reporter>`, one line, at most 120 characters; the text gives way first. */
+export declare function issueTitle(wording: IssueWording, text: string, name: string): string;
+/** The reporter's own words with credential shapes masked, bounded. */
+export declare function cleanText(mask: Mask, text: string): string;
+/** Hidden in the issue or comment, so a retry can tell that an earlier attempt got through. */
+export declare function retryMarker(report: Pick<ReportText, "id" | "createdAt">): string;
+/** The web console's page of a session. */
+export declare function sessionLink(publicBaseUrl: string, sessionId: string): string;
+export declare function issueBody(wording: IssueWording, publicBaseUrl: string, report: ReportText): string;
+/** The comment a second report in the same session within the dedupe window becomes. */
+export declare function commentBody(report: ReportText): string;
+/** The reporter's last question and answer, added at their request: masked, bounded, fenced. */
+export declare function conversationComment(mask: Mask, question: string, answer: string): string;

package/dist/types/feedback/log-text.d.ts

@@ -0,0 +1,13 @@
+import type { LogFields, LogLevel } from "../ports/logger.js";
+import type { Mask } from "./issue-text.js";
+export declare function safeLogText(mask: Mask, message: string, fields?: LogFields): string;
+/** One kept line: when, how severe, which part of the worker, and its safe text. */
+export interface KeptLogLine {
+    /** Seconds since the epoch. */
+    readonly at: number;
+    readonly level: LogLevel;
+    readonly logger: string;
+    readonly text: string;
+}
+/** `<UTC time> <LEVEL> <logger> <text>`, as the scene lists it. */
+export declare function renderLogLine(line: KeptLogLine): string;

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

@@ -0,0 +1,4 @@
+/** An inline code span: one line, no backtick, no opening of an HTML comment, at most 120 characters. */
+export declare function code(value: string | number): string;
+/** A fenced block whose fence is longer than any run of backticks inside it. */
+export declare function fence(text: string, info?: string): string;

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

@@ -0,0 +1,25 @@
+import type { IdentityLookup } from "../plugins/identity-lookup.js";
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { RouteBase } from "../ports/routing.js";
+import type { SessionRepository } from "../ports/store/sessions.js";
+import { type OutMessage, type UserRef } from "../ports/surface.js";
+import type { FeedbackService, ReportResult } from "./service.js";
+export interface ReportingDeps {
+    readonly service: FeedbackService;
+    readonly sessions: Pick<SessionRepository, "getSession">;
+    /** The person's Claw credential if they have one; never asks them for it (`undefined`: not linked). */
+    readonly credential: (sender: UserRef) => Promise<string | undefined>;
+    readonly identity: IdentityLookup;
+    readonly clock: Clock;
+    readonly log: Logger;
+}
+export declare function replyText(result: ReportResult): string;
+export declare class FeedbackReporting {
+    private readonly deps;
+    constructor(deps: ReportingDeps);
+    file(route: RouteBase, text: string): Promise<void>;
+    /** What the channel gave, and for what is missing, what the key's platform says; a slow or failed lookup is skipped. */
+    private reporterOf;
+}
+export declare function offerMessage(offerId: string, issueNumber: number): OutMessage;

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

@@ -0,0 +1,65 @@
+/**
+ * The scene of a report: who and where, the chat's last turns, the worker's last log lines for that chat. Recorded
+ * without asking, so it carries ids, states, counts and tool names only, never what anybody wrote: every value taken
+ * from an event is an enumerated field or an identifier-shaped token (`tokenOf`).
+ */
+export declare const LAST_TURNS = 2;
+export declare const LOG_LINES = 30;
+/** One event of a session's history, as Claw's replay gives it (the stream's history has no `created_at`). */
+export interface HistoryRow {
+    readonly event_id: string;
+    readonly event_type: string;
+    readonly data: unknown;
+    readonly created_at: unknown;
+}
+/** An event of a turn: its id, type, data object and time (seconds since the epoch; undefined when not known). */
+export interface TurnEvent {
+    readonly id: string;
+    readonly type: string;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly at: number | undefined;
+}
+export type TurnStatus = "finished" | "failed" | "stopped" | "stuck" | "running" | "unfinished";
+export interface TurnSummary {
+    readonly turnId: string;
+    readonly status: TurnStatus;
+    readonly seconds: number | undefined;
+    readonly tools: readonly string[];
+    readonly toolErrors: number;
+    readonly errors: readonly string[];
+}
+export interface Scene {
+    readonly name: string;
+    readonly platformUserId: string;
+    /** "1:1" or "group". */
+    readonly chat: string;
+    /** Seconds since the epoch. */
+    readonly at: number;
+    readonly sessionId: string;
+    readonly pluginId: string;
+    readonly workerVersion: string;
+    readonly workerImage: string;
+    readonly apiImage: string;
+    readonly brainImage: string;
+    /** Whether the session runs a turn now; undefined when that could not be read. */
+    readonly busy: boolean | undefined;
+    readonly turns: readonly TurnSummary[];
+    /** Why there are no turns, when there are none. */
+    readonly turnsNote: string;
+    readonly logs: readonly string[];
+}
+export declare function objectOf(value: unknown): Readonly<Record<string, unknown>>;
+/** A timestamp as Claw writes it (epoch seconds or milliseconds, or ISO 8601 as Python reads it), in seconds. */
+export declare function secondsOf(value: unknown): number | undefined;
+/** The session's events grouped by turn: a turn starts at a UserMessage and runs to the next one. */
+export declare function splitTurns(rows: readonly HistoryRow[]): TurnEvent[][];
+/** The id of a turn: the message id of its UserMessage, else that event's id. */
+export declare function turnIdOf(events: readonly TurnEvent[]): string;
+/** Status, duration, tool names and errors of one turn, from event types and a few enumerated fields only. */
+export declare function summarizeTurn(events: readonly TurnEvent[], now: number): TurnSummary;
+/** The last `LAST_TURNS` turns of a history, summarized. */
+export declare function lastTurns(rows: readonly HistoryRow[], now: number): TurnSummary[];
+/** The scene as the issue shows it. */
+export declare function sceneMarkdown(scene: Scene): string;
+/** The newest turn of the scene: what "my last question and answer" means. */
+export declare function lastTurnId(scene: Scene): string;