@primusclaw/personal-agent 0.0.0-stage → 0.1.1

package/dist/types/remote-view/agents-view.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The agents card (`/agents`): per machine its agents, per online agent a "New session" form (a folder from the roots it reported,
+ * a subfolder to type, one button) and the conversations it offers, then the user's sessions with Attach / Detach / Close. Every
+ * button carries {"primusclaw": "remote", "op": ...}; the worker checks every click against Claw's own lists, never against the card.
+ */
+import type { AgentsInput } from "../remote/ports.js";
+import type { Lang } from "../locales/lang.js";
+import { type RemoteButton } from "../remote/actions.js";
+import { type ApprovalInput } from "./machine-views.js";
+import { type ConversationItem } from "./conversations-view.js";
+/** Where a new session starts: a choice of the roots the agent reported and a subfolder, or (none reported) the whole folder. */
+export type StartFolder = {
+    readonly kind: "roots";
+    readonly label: string;
+    readonly roots: readonly {
+        title: string;
+        value: string;
+    }[];
+    readonly subfolder: FolderInput;
+} | {
+    readonly kind: "folder";
+    readonly input: FolderInput;
+};
+export interface FolderInput {
+    readonly label: string;
+    readonly placeholder: string;
+    readonly maxLength: number;
+}
+/** One online agent's block. Input ids carry the slot: a card's inputs all come back with every button. */
+export interface AgentBlock {
+    readonly kind: "agent";
+    readonly slot: number;
+    /** `icon name`, inert. */
+    readonly title: string;
+    readonly unattendedNote: string | null;
+    /** null for an agent of kind `attach`, which starts no conversation of its own. */
+    readonly start: {
+        readonly folder: StartFolder;
+        readonly approval: ApprovalInput | null;
+        readonly button: RemoteButton;
+    } | null;
+    readonly conversations: readonly ConversationItem[];
+    readonly nothingToTakeOver: string | null;
+}
+export interface SessionRow {
+    readonly kind: "session";
+    readonly number: number;
+    readonly line: string;
+    readonly buttons: readonly RemoteButton[];
+}
+export type AgentsItem = {
+    readonly kind: "lead";
+    readonly text: string;
+} | {
+    readonly kind: "machine";
+    readonly text: string;
+    readonly separator: boolean;
+} | {
+    readonly kind: "versionNote";
+    readonly text: string;
+} | {
+    readonly kind: "problems";
+    readonly lines: readonly string[];
+} | {
+    readonly kind: "subtle";
+    readonly text: string;
+} | AgentBlock | {
+    readonly kind: "heading";
+    readonly text: string;
+} | SessionRow | {
+    readonly kind: "plain";
+    readonly text: string;
+} | {
+    readonly kind: "footer";
+    readonly text: string;
+};
+export interface AgentsView {
+    readonly lang: Lang;
+    /** false: the sessions part alone (`/agent sessions`). */
+    readonly machines: boolean;
+    readonly title: string;
+    readonly items: readonly AgentsItem[];
+    readonly actions: readonly RemoteButton[];
+    /** The session ids it lists in order: the numbers of `/agent attach N`. */
+    readonly listing: readonly string[];
+}
+/** The agents card as a view: what it says and what each button does. */
+export declare function agentsView(input: AgentsInput): AgentsView;

package/dist/types/remote-view/conversations-view.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The conversations an agent offers on the agents card, in three groups: those a terminal has open now (shared, never taken from
+ * it: Connect or Watch only, or, when this chat is connected to it, that and Disconnect); below them, labelled, those no process
+ * runs (Take over) and those the connector cannot tell. One this connector already holds for a session of this chat is not listed.
+ */
+import type { Lang } from "../locales/lang.js";
+import { type RemoteButton } from "../remote/actions.js";
+import { type Conversation } from "../remote/conversations.js";
+import type { Agent, Connector } from "../remote/model.js";
+export type ConversationItem = 
+/** Its title (inert, or "Untitled") and, under it, its folder and how long ago. */
+{
+    readonly kind: "conversation";
+    readonly title: string;
+    readonly where: string;
+}
+/** A small subtle line right under the conversation. */
+ | {
+    readonly kind: "note";
+    readonly text: string;
+} | {
+    readonly kind: "buttons";
+    readonly buttons: readonly RemoteButton[];
+}
+/** The label of a group, with a separator above it when something is listed before it. */
+ | {
+    readonly kind: "group";
+    readonly text: string;
+    readonly separator: boolean;
+} | {
+    readonly kind: "more";
+    readonly text: string;
+};
+/** The line under a conversation open in a terminal: what connecting to it does, and when the phone can only watch, why and
+ * what to change. */
+export declare function shareNote(agent: Agent, entry: Conversation, lang: Lang): string;
+/** The one button a conversation open in a terminal offers: connect, when what is sent is typed into that terminal; else watch. */
+export declare function shareButton(agent: Agent, entry: Conversation, lang: Lang): {
+    title: string;
+    style: "positive" | null;
+};
+/** The conversations of one online agent on the agents card. */
+export declare function conversationItems(connector: Connector, agent: Agent, now: number, lang: Lang, joined: {
+    readonly connected: ReadonlyMap<string, {
+        readonly number: number;
+        readonly sessionId: string;
+    }>;
+    readonly mine: ReadonlySet<string>;
+}): ConversationItem[];
+/** How many of an agent's conversations its owner hid here (Claw leaves them out of the list and counts them), or 0. */
+export declare function hiddenCount(agent: Agent): number;

package/dist/types/remote-view/hidden-view.d.ts

@@ -0,0 +1,20 @@
+/** The conversations hidden on one machine, each with Unhide; then Unhide all and Back to the list. */
+import type { Lang } from "../locales/lang.js";
+import type { Connector } from "../remote/model.js";
+import { type RemoteButton } from "../remote/actions.js";
+/** Hidden conversations one card lists (a connector reports at most twelve per agent). */
+export declare const HIDDEN_SHOWN = 20;
+export interface HiddenView {
+    readonly lang: Lang;
+    readonly title: string;
+    readonly entries: readonly {
+        readonly title: string;
+        readonly where: string;
+        readonly unhide: RemoteButton;
+    }[];
+    /** Said when nothing is hidden; null otherwise. */
+    readonly nothing: string | null;
+    readonly actions: readonly RemoteButton[];
+}
+/** The hidden conversations of `connector` (from a listing with them included). */
+export declare function hiddenView(connector: Connector, now: number, lang?: Lang): HiddenView;

package/dist/types/remote-view/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What a person sees of a remote agent (a coding agent on their own machine, reached through Claw's remote-agents API): reading
+ * its events, the live view of a turn, the lines a chat attached to it is told, and the views of its cards. Nothing here talks
+ * to Claw or a channel.
+ */
+import type { AgentsView } from "./agents-view.js";
+import type { DisconnectView, MachineChoiceView, ModeView, TakeoverView } from "./machine-views.js";
+import type { DecidedView, PermissionView, RemoteAskView } from "./permission-view.js";
+import type { SessionsView } from "./sessions-view.js";
+import type { StatusView } from "./status-view.js";
+import type { HiddenView } from "./hidden-view.js";
+import type { WindowCardView } from "./window-view.js";
+export * from "./agents-view.js";
+export * from "./conversations-view.js";
+export * from "./hidden-view.js";
+export * from "./live-view.js";
+export * from "./machine-views.js";
+export * from "./permission-view.js";
+export * from "./sessions-view.js";
+export * from "./status-view.js";
+export * from "./window-view.js";
+export { remoteHealthText, remoteOffText, remoteQueuedText, remoteStopText, remoteText } from "../locales/remote.js";
+export { remoteWindowCardText } from "../locales/remote-window-card.js";
+declare module "../ports/surface.js" {
+    interface ViewMap {
+        remoteAgents: AgentsView;
+        remoteSessions: SessionsView;
+        remoteStatus: StatusView;
+        remotePermission: PermissionView;
+        remoteAsk: RemoteAskView;
+        remoteDecided: DecidedView;
+        remoteDisconnect: DisconnectView;
+        remoteTakeover: TakeoverView;
+        remoteMachineChoice: MachineChoiceView;
+        remoteMode: ModeView;
+        remoteWindow: WindowCardView;
+        remoteHidden: HiddenView;
+    }
+}
+export { createRemoteViews } from "./messages.js";

package/dist/types/remote-view/live-view.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What a chat shows while a remote agent works: its own text as it streams, its thoughts as dim italic lines, one line for the
+ * plan, a line for a step that failed and one running line for the step running now. Bounded like Claw's own live view (the
+ * newest part that fits is kept). Credentials are masked at render time over the whole text, so a secret split across two
+ * chunks is still caught.
+ */
+import type { RemoteStep } from "../remote/events.js";
+import type { Lang } from "../locales/lang.js";
+/** The live view of a turn shows at most this much below its header. */
+export declare const LIVE_MAX_CHARS = 2500;
+/** Blocks a live view keeps (a long turn does not grow it without bound). */
+export declare const LIVE_KEEP_BLOCKS = 40;
+/** The mark of the one line of the step that is running now. */
+export declare const RUNNING_MARK = "\u23F3";
+/** The newest paragraphs that fit `budget` characters, "..." when older ones were left out, and an unclosed code fence closed. */
+export declare function boundedBody(paragraphs: readonly string[], budget: number): string;
+export declare class RemoteLiveView {
+    readonly lang: Lang;
+    /** The first line of every render: who is working. */
+    readonly header: string;
+    private readonly blocks;
+    /** Tool call id -> title of the steps in flight, oldest first. */
+    private readonly active;
+    /** The next text starts a new block (a tool ran since the last one). */
+    private split;
+    /** Why the message waits, while it waits for a terminal on the machine (`terminal_input_queued`, said in the chat's language by
+     * the runner): the floating status says it, not only "Thinking…", until anything of the turn shows. */
+    private waiting;
+    constructor(label: string, lang?: Lang);
+    /** Fold one step in; true when what `render` returns changed. */
+    apply(step: RemoteStep): boolean;
+    /** The few short lines of Teams' floating status while the agent works: why the message still waits for the terminal, where
+     * its plan stands, a step that failed last, and the step running now. Its words are streamed into the answer's bubble, not
+     * into the status. */
+    statusLines(): string[];
+    /** The header and the newest part of the turn that fits. */
+    render(): string;
+    private addText;
+    private trackTool;
+    private setPlan;
+    private runningLine;
+    private paragraph;
+    private paragraphs;
+}

package/dist/types/remote-view/machine-views.d.ts

@@ -0,0 +1,73 @@
+/** The smaller cards of the remote agents: disconnecting a machine, taking over a terminal's conversation, picking an agent on a
+ * machine, picking a mode. */
+import type { Lang } from "../locales/lang.js";
+import { type RemoteButton } from "../remote/actions.js";
+import { type Approval } from "../remote/agents.js";
+import type { Conversation } from "../remote/conversations.js";
+import type { Agent, Connector } from "../remote/model.js";
+import type { ConnectorSetupWords } from "../remote/setup.js";
+export interface DisconnectView {
+    readonly lang: Lang;
+    readonly title: string;
+    /** How to connect it again. */
+    readonly again: string;
+    /** The exact login command (a machine that signed in with login), null for a paired machine. */
+    readonly login: string | null;
+    readonly connectorId: string;
+    readonly confirm: string;
+    readonly keep: string;
+}
+/** Asks before a machine is disconnected: it ends every session on it, and says how to connect it again. `paired`: Claw says the
+ * machine was connected with a pairing code; a login command is no use there. */
+export declare function disconnectView(host: string, connectorId: string, setup: ConnectorSetupWords, lang?: Lang, paired?: boolean): DisconnectView;
+export interface TakeoverView {
+    readonly lang: Lang;
+    readonly title: string;
+    readonly conversation: string;
+    /** `host · folder`. */
+    readonly where: string;
+    readonly what: string;
+    readonly oneSide: string;
+    readonly buttons: readonly RemoteButton[];
+}
+/** What a tap on Take over… for a conversation open in a terminal opens: what will happen, in so many words, then Take over and
+ * Cancel. `ticket`: what the confirmation carries ("1" when none). */
+export declare function takeoverView(connector: Connector, agent: Agent, entry: Conversation, lang?: Lang, view?: string, ticket?: string): TakeoverView;
+export interface ApprovalInput {
+    readonly id: string;
+    readonly label: string;
+    readonly value: Approval;
+    readonly choices: readonly {
+        readonly title: string;
+        readonly value: Approval;
+    }[];
+}
+/** The choice between asking for approval and not, for an agent whose connector lets a client switch; null otherwise. */
+export declare function approvalInput(agent: Agent, slot: number, lang: Lang): ApprovalInput | null;
+export interface MachineChoiceView {
+    readonly lang: Lang;
+    readonly title: string;
+    readonly worksIn: string;
+    readonly agents: readonly {
+        readonly unattendedNote: string | null;
+        readonly approval: ApprovalInput | null;
+        readonly button: RemoteButton;
+    }[];
+    readonly more: string | null;
+}
+/** `/agent new MACHINE PATH` named a machine with more than one online agent: a block per agent, each starting the session in
+ * `path`. The folder is not in the buttons: the worker keeps what was typed under `token`, so a card cannot choose it. */
+export declare function machineChoiceView(connector: Connector, agents: readonly Agent[], token: string, path: string, lang?: Lang): MachineChoiceView;
+export interface ModeView {
+    readonly lang: Lang;
+    readonly title: string;
+    readonly value: string;
+    readonly choices: readonly {
+        readonly title: string;
+        readonly value: string;
+    }[];
+    readonly setMode: RemoteButton;
+    readonly back: RemoteButton;
+}
+/** What a tap on Mode opens: the modes the connector reports (one that runs without asking for approval says so), Set mode, Back. */
+export declare function modeView(sessionId: string, current: string | null, modes: readonly string[], unattended?: ReadonlySet<string>, lang?: Lang): ModeView;

package/dist/types/remote-view/messages.d.ts

@@ -0,0 +1,3 @@
+import type { RemoteViews } from "../remote/ports.js";
+/** The view the assembly gives the remote agents (`RemoteContext.views`). */
+export declare function createRemoteViews(): RemoteViews;

package/dist/types/remote-view/permission-view.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The cards of a remote agent's permission request: the one an attached chat gets (`permissionRequest`), the push of an agent
+ * that waits on the user for an instruction the assistant sent (`remote.ask`), and what either becomes once answered. The card is
+ * not trusted: the click is checked against the stored options, never against the card.
+ */
+import type { Lang } from "../locales/lang.js";
+import type { DecisionButton } from "../remote/actions.js";
+import { type PermissionOption } from "../remote/options.js";
+import type { Reported } from "../remote/reported.js";
+/** The buttons of a permission card: one per offered option, in the fixed order, each carrying the option's own id. */
+export declare function optionButtons(options: readonly PermissionOption[], sessionId: string, actionId: string, lang?: Lang): DecisionButton[];
+export interface PermissionView {
+    readonly lang: Lang;
+    /** What the agent wants to do (its own title, inert). */
+    readonly action: string;
+    /** Its input, kept whole but unable to make a link or a tag. */
+    readonly input: unknown;
+    /** Whose agent asks, and of what kind the request is. */
+    readonly asking: string;
+    readonly notes: readonly string[];
+    readonly buttons: readonly DecisionButton[];
+}
+/** The card for one `permissionRequest`. `who`: whose agent it is; `zone`: the user's time zone (an IANA name). */
+export declare function permissionView(request: Reported, options: readonly PermissionOption[], sessionId: string, who: string, expiresAt: number, zone: string, lang?: Lang): PermissionView;
+export interface RemoteAskView {
+    readonly lang: Lang;
+    readonly title: string;
+    /** The tool, inert, in bold. */
+    readonly tool: string;
+    /** Whose agent waits, and for which errand. */
+    readonly waits: string;
+    readonly notes: readonly string[];
+    readonly buttons: readonly DecisionButton[];
+}
+export interface RemoteAsk {
+    /** The ask as Claw relayed it (`assistant.say` `remote.ask`): its `action_id` and `tool`. */
+    readonly ask: Reported;
+    readonly options: readonly PermissionOption[];
+    readonly sessionId: string;
+    readonly machine: string;
+    readonly agent: string;
+    /** Which errand: `#seq title`. */
+    readonly about: string;
+    readonly expiresAt: number;
+    readonly zone: string;
+}
+/** The push for an agent on the user's machine that waits on them (an instruction the assistant sent). */
+export declare function remoteAskView(input: RemoteAsk, lang?: Lang): RemoteAskView;
+export interface DecidedView {
+    readonly lang: Lang;
+    readonly title: string;
+    readonly allowed: boolean;
+}
+/** What a permission card becomes once the user chose `option` at `when`. */
+export declare function decidedView(option: PermissionOption, when: number, zone: string, lang?: Lang): DecidedView;

package/dist/types/remote-view/sessions-view.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The sessions card: every session the user has, per machine (an offline one says since when) and per agent: its active sessions
+ * with "Switch to it" (the one the chat is on says so) and Close, then the conversations it offers; one a terminal has open says
+ * how it is shared. Whatever needs the user comes first and says so: a session with an approval card open (`waiting`) and a
+ * conversation whose terminal waits for its person; a line under the title counts them.
+ */
+import type { SessionsInput } from "../remote/ports.js";
+import type { Lang } from "../locales/lang.js";
+import { type RemoteButton } from "../remote/actions.js";
+import type { ConnectSteps } from "../remote/setup.js";
+export type AgentRow = 
+/** A session of the user's, numbered (`row-session-N`), and its buttons. */
+{
+    readonly kind: "session";
+    readonly number: number;
+    readonly line: string;
+    readonly buttons: readonly RemoteButton[];
+} | {
+    readonly kind: "more";
+    readonly text: string;
+}
+/** A conversation the agent offers (`row-conv-N`, N counted over the whole card). */
+ | {
+    readonly kind: "conversation";
+    readonly rowId: number;
+    readonly line: string;
+} | {
+    readonly kind: "buttons";
+    readonly buttons: readonly RemoteButton[];
+} | {
+    readonly kind: "note";
+    readonly text: string;
+};
+export type SessionsItem = {
+    readonly kind: "lead";
+    readonly text: string;
+} | {
+    readonly kind: "badge";
+    readonly text: string;
+} | {
+    readonly kind: "machine";
+    readonly text: string;
+    readonly online: boolean;
+} | {
+    readonly kind: "versionNote";
+    readonly text: string;
+} | {
+    readonly kind: "subtle";
+    readonly text: string;
+}
+/** One agent (`row-agent-N`): its title and rows. */
+ | {
+    readonly kind: "agent";
+    readonly rowId: number;
+    readonly title: string;
+    readonly rows: readonly AgentRow[];
+} | {
+    readonly kind: "connect";
+    readonly steps: ConnectSteps;
+};
+export interface SessionsView {
+    readonly lang: Lang;
+    readonly title: string;
+    readonly items: readonly SessionsItem[];
+    readonly actions: readonly RemoteButton[];
+    /** The active session ids in the order shown: the numbers of `/agent attach N`. */
+    readonly listing: readonly string[];
+}
+/** The sessions card as a view. */
+export declare function sessionsView(input: SessionsInput): SessionsView;

package/dist/types/remote-view/status-view.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The status card of a chat that talks to a remote session: ONE card that says where its messages go (which machine and agent,
+ * the folder, whether the agent is working, and when that was last true). It is sent once, when the chat attaches, and after that
+ * only edited in place. Its buttons are the system operations (switch, back to the assistant, stop, mode), so the chat itself
+ * holds only the conversation with the agent. Every button names the session, which the worker checks against the chat's own.
+ */
+import type { StatusInput } from "../remote/ports.js";
+import type { Lang } from "../locales/lang.js";
+import { type RemoteButton } from "../remote/actions.js";
+/** Each line of the status card, by what it says. */
+export type StatusLine = {
+    readonly kind: "lead";
+    readonly text: string;
+}
+/** Where the named conversation runs, under the title. */
+ | {
+    readonly kind: "where";
+    readonly text: string;
+} | {
+    readonly kind: "lastSession";
+    readonly text: string;
+} | {
+    readonly kind: "folder";
+    readonly text: string;
+} | {
+    readonly kind: "phase";
+    readonly text: string;
+} | {
+    readonly kind: "unattended";
+    readonly text: string;
+}
+/** Which messages stay with the assistant. */
+ | {
+    readonly kind: "assistant";
+    readonly text: string;
+} | {
+    readonly kind: "updated";
+    readonly text: string;
+};
+export interface StatusView {
+    readonly lang: Lang;
+    readonly title: string;
+    /** Attached: the accent band; back at the assistant or ended: none. */
+    readonly tone: "accent" | "default";
+    /** In order; the lead, when there is one, comes before the title. */
+    readonly lines: readonly StatusLine[];
+    readonly buttons: readonly RemoteButton[];
+    /** The chat's system operations must each stay one tap away: this card alone may carry four. */
+    readonly buttonsMax: number;
+}
+/** The chat's status card as a view. */
+export declare function statusView(input: StatusInput): StatusView;

package/dist/types/remote-view/window-view.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The session card as the window (Python `session_window.window_card`): where the session runs and how it stands, the end of its
+ * output (more behind a toggle, the whole as messages), what waits for the person, and the text box while it is idle. Every word
+ * an agent or its connector supplied is inert. The window's state and policy (WindowView, takesInput, what is shown of the output)
+ * are the remote domain's (`remote/window/`); this says what the card shows.
+ */
+import type { WindowInput } from "../remote/ports.js";
+import type { Lang } from "../locales/lang.js";
+import { type DecisionButton, type RemoteButton } from "../remote/actions.js";
+/** The output the card shows at once (a phone screen of it), and behind its "more" toggle. */
+export declare const TAIL_CHARS = 900;
+export declare const TAIL_LINES = 14;
+export declare const MORE_CHARS = 3500;
+export declare const MORE_LINES = 60;
+/** What the person sent from the card, shown back on it. */
+export declare const SENT_SHOWN_CHARS = 200;
+export declare const APPROVALS_SHOWN = 3;
+/** One line of output (a minified file is not one card). */
+export declare const LINE_MAX = 400;
+/** One line of the agent's output as a TextBlock shows it: control characters gone, no link or tag can be built from it (an
+ * address in it broken where it stands, as in a short line: the output is shown as the agent wrote it, not made words as an
+ * answer is, so a code span made for a host would only show its backticks), the markdown a TextBlock reads escaped, never read
+ * as a list item, clipped. */
+export declare function outputLine(raw: string): string;
+export interface WindowOutput {
+    /** The end of the output, line by line (inert); empty with `empty` said instead. */
+    readonly lines: readonly string[];
+    readonly empty: string | null;
+    /** The lines before them, behind the toggle (null: nothing more to show). */
+    readonly more: readonly string[] | null;
+    readonly moreToggle: string;
+    /** Full output and Mode, under the output. */
+    readonly buttons: readonly RemoteButton[];
+}
+export interface WindowCardView {
+    readonly lang: Lang;
+    readonly lead: string;
+    readonly title: string;
+    readonly waiting: boolean;
+    /** The conversation, folder and mode, in one subtle line ("" for none). */
+    readonly sub: string;
+    readonly state: string;
+    readonly unattended: string | null;
+    readonly sent: string | null;
+    readonly output: WindowOutput;
+    readonly note: string | null;
+    readonly approvals: readonly {
+        readonly text: string;
+        readonly buttons: readonly DecisionButton[];
+    }[];
+    readonly moreApprovals: string | null;
+    readonly groupNote: string | null;
+    /** The text box, while the session takes input; null otherwise. */
+    readonly box: {
+        readonly id: string;
+        readonly placeholder: string;
+        readonly value: string;
+        readonly maxLength: number;
+    } | null;
+    readonly boxNote: string | null;
+    readonly chatBox: string;
+    readonly updated: string;
+    readonly actions: readonly RemoteButton[];
+    /** Whether the card carries the text box (what a later refresh reads instead of the card's JSON). */
+    readonly takesInput: boolean;
+}
+/** The session card as a view. */
+export declare function windowView(input: WindowInput): WindowCardView;

package/dist/types/result.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The result of an operation that can fail in a way its caller is expected to handle.
+ *
+ * The convention for the whole package:
+ *  - An expected failure (the identity service says "not bound", Teams refuses a stream, a card's data is not what the
+ *    handler reads) is a value: `Result<T, E>` where `E` is a discriminated union with a `kind` field. The caller has
+ *    to look at it; the compiler sees a case it forgot.
+ *  - A broken invariant (a bug, a programming error) is thrown, as an `Error`. Nothing catches it to continue as if the
+ *    operation had worked; the one place that catches everything (the handler of one inbound event) logs its type and
+ *    tells the person the request did not finish.
+ *  - Nothing swallows an error: a `catch` that continues returns or records what it caught.
+ */
+export type Result<T, E extends Failure> = Ok<T> | Err<E>;
+/** What every expected failure carries: which one it is. */
+export interface Failure {
+    readonly kind: string;
+}
+export interface Ok<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export interface Err<E extends Failure> {
+    readonly ok: false;
+    readonly error: E;
+}
+export declare function ok<T>(value: T): Ok<T>;
+export declare function err<E extends Failure>(error: E): Err<E>;
+/** The value of a result, or `fallback` when it failed. */
+export declare function valueOr<T, E extends Failure>(result: Result<T, E>, fallback: T): T;
+/** A result whose value went through `fn`; a failure passes through unchanged. */
+export declare function mapResult<T, U, E extends Failure>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;

package/dist/types/review/connect/connections.d.ts

@@ -0,0 +1,24 @@
+/** What /whoami says the person is connected to: SaFE, GitHub (what Clawy reads it with), the deployment's own lines, memory. */
+import type { GithubConnection } from "../../claw/model.js";
+import type { GithubState } from "../../ports/github.js";
+/** A part that could not be read just now. */
+export declare const UNKNOWN: unique symbol;
+export interface ConnectionsInput {
+    /** The SaFE account the chat is linked to; null when it could not be read. */
+    readonly safe: {
+        readonly name: string;
+    } | null;
+    /** The binding at the identity service; null: none (or no `/github` here); UNKNOWN. */
+    readonly githubState: GithubState | null | typeof UNKNOWN;
+    /** Claw's answer; null with `connectionKnown` for a Claw that cannot say, null without it when it could not be asked. */
+    readonly connection: GithubConnection | null;
+    readonly connectionKnown: boolean;
+    readonly githubPart: boolean;
+    /** (enabled, available), or UNKNOWN. */
+    readonly memory: readonly [boolean, boolean] | typeof UNKNOWN;
+    readonly memoryPage: string;
+    readonly zh: boolean;
+    /** The lines a deployment's integrations add. */
+    readonly extraLines: readonly string[];
+}
+export declare function connectionsText(p: ConnectionsInput): string;