@opencode-cockpit/trust 0.0.0-stage → 0.8.0

package/types/core/rules.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What `opencode.json` says about a permission, read the way OpenCode reads it.
+ *
+ * Trust only ever sees the gap config left open (docs/opencode/permissions.md): `deny` never emits an
+ * event and `allow` never needs one. Inside that gap there are two kinds of "ask", and telling them
+ * apart is this file's job:
+ *
+ * - **a catch-all** — `"bash": "ask"`, `{ "bash": { "*": "ask" } }`, or no rule at all — is a default:
+ *   "I have not decided about these". Trust may fill it.
+ * - **a specific pattern set to ask** — `"git push *": "ask"` — is a decision: "always ask me about
+ *   this one". Trust never answers it.
+ *
+ * Matching is OpenCode's own: its wildcard (`*` any run, `?` one character, and a trailing ` *` that
+ * also matches nothing, so `ls *` covers `ls`), evaluated over the ordered rules, last match wins.
+ * The merge across files is OpenCode's too — v1 hands over the merged config; v2 hands over its
+ * documents in priority order, and concatenating their rules in that order keeps "last match wins"
+ * meaning what it meant.
+ */
+export type Action = "allow" | "deny" | "ask";
+export interface ConfigRule {
+    /** Permission name, canonical (`bash`, never `shell`); may be a wildcard such as `*`. */
+    permission: string;
+    pattern: string;
+    action: Action;
+}
+export declare const canonical: (permission: string) => string;
+/** OpenCode's `Wildcard.match`, as in `util/wildcard.ts`. */
+export declare function match(text: string, pattern: string): boolean;
+/**
+ * The rules in force for an agent, from whatever `config.get` returned: v1's merged config, or v2's
+ * list of documents (`{ type: "document", info }`, lowest priority first). The agent's rules come last
+ * because OpenCode lays them over the global ones.
+ */
+export declare function rulesFrom(config: unknown, agent?: string): ConfigRule[];
+/** The rule that decides `text` for `permission`, as OpenCode picks it: the last that matches. */
+export declare function evaluate(rules: readonly ConfigRule[], permission: string, text: string): ConfigRule | undefined;
+/**
+ * What config means for one pattern of a request.
+ *
+ * `open` — nothing decided it, or a catch-all said ask: Trust's to fill.
+ * `allowed` — config allows it; the request asked because of something else in it.
+ * `held` — you asked to be asked (a specific `ask`), or config denies it: Trust stays out.
+ */
+export type Gate = {
+    kind: "open";
+} | {
+    kind: "allowed";
+    rule: ConfigRule;
+} | {
+    kind: "held";
+    rule: ConfigRule;
+};
+export declare function gate(rules: readonly ConfigRule[], permission: string, text: string): Gate;
+/** A rule as you would have written it, for a reason shown to you. */
+export declare function describeRule(rule: ConfigRule): string;

package/types/core/sample.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Sample worlds for the preview and the grid test: the states a design gets wrong
+ * (docs/building/testing.md) — nothing at all, a first week, a busy project, a paused one, one
+ * where something broke, and one grouped into families with one of them widened by hand.
+ *
+ * Each is built by running the real engine over real requests, so the preview shows what the
+ * engine actually produces rather than what a hand-written state hoped it would.
+ */
+import { type Engine } from "./engine.ts";
+export declare const SAMPLE_ROOT = "/work/app";
+export declare const SAMPLE_NOW = 1790300000000;
+export declare const SAMPLE_SETTINGS: {
+    threshold: number;
+    dangerExtra: number;
+    expireDays: number;
+    keep: number;
+};
+export interface Sample {
+    engine: Engine;
+    trouble?: string;
+}
+export declare const SAMPLES: Record<string, () => Sample>;

package/types/core/shell.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A command line, read the way Trust needs it: split into the commands it runs, each as words.
+ *
+ * Not a shell. It has one job and one direction to fail in: anything it cannot read *for certain* —
+ * an expansion, a substitution, a subshell, a heredoc, a program that runs a string it was handed —
+ * comes back `opaque`, and an opaque line is always asked. A reader that guesses would let the one
+ * line it misread be approved by the approvals of another.
+ *
+ * Why not OpenCode's tree-sitter: one runtime dependency per package (docs/building/a-new-bay.md),
+ * and a grammar still has to be told what "cannot be known statically" means — which is this file.
+ */
+export interface Command {
+    /** `NAME=value` words before the program. They change what it does, so they are part of it. */
+    env: string[];
+    /** The program and its arguments, quotes removed. */
+    argv: string[];
+    /** Where it runs when an earlier `cd` on the same line moved it; absolute or relative as written. */
+    cwd?: string;
+    /**
+     * Which `argv` words are redirections the shell acts on (`>`, `2>&1`), as opposed to the same
+     * characters quoted as an argument: `echo '>' x` writes nothing, `echo > x` writes a file, and by
+     * text alone the two were one command. Absent on a command built by hand: then the text decides.
+     */
+    redirects?: number[];
+}
+export type Parsed = {
+    kind: "commands";
+    commands: Command[];
+} | {
+    kind: "opaque";
+    reason: string;
+};
+/**
+ * Reads a command line into the commands it runs.
+ *
+ * `cd` is not returned as a command — it asks nothing by itself, as in OpenCode — but it moves every
+ * command after it, and that is kept: `cd build && rm -rf *` and `cd /tmp && rm -rf *` are different
+ * lines and must never share an approval.
+ */
+export declare function parse(line: string): Parsed;

package/types/core/signature.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What an approval is an approval *of*.
+ *
+ * A signature is the command exactly as it will run — environment, program, every argument in order,
+ * and where it runs — with quoting normalised so that `echo 'a b'` and `echo "a b"` are one thing.
+ * Nothing is generalised away. OpenCode's own "always" generalises, and measured on its own arity
+ * table, `docker compose -p cockpit up -d` and `docker compose -p prod down -v` both became
+ * `docker compose -p *` (docs/opencode/permissions.md). A signature can only ever match the command
+ * that earned it; making one cover more is something a person does, in the ledger, on purpose.
+ */
+import type { Command } from "./shell.ts";
+export declare function quote(word: string): string;
+/**
+ * Where a command runs, said relative to the project: `cd /path/to/project && git status` is
+ * `git status`. A directory outside the project stays absolute, so it cannot pass for one inside.
+ */
+export declare function place(cwd: string | undefined, root: string | undefined): string | undefined;
+export declare function signature(command: Command, root?: string): string;

package/types/core/view/actions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What `x`, `w` and `c` do, on whatever is selected — a command, a family, an answer in the feed, or
+ * OpenCode's own "always". Pure: each returns the events to append and the sentence to say. Nothing
+ * in the ledger is ever changed in place.
+ */
+import type { Answer } from "../history.ts";
+import type { Event } from "../ledger.ts";
+import { type AlwaysGroup, type Command, type Family, type Reading } from "./model.ts";
+import type { Tone } from "./rows.ts";
+export type Target = {
+    kind: "command";
+    command: Command;
+    family?: Family;
+} | {
+    kind: "family";
+    family: Family;
+} | {
+    kind: "answer";
+    answer: Answer;
+} | {
+    kind: "always";
+    groups: AlwaysGroup[];
+};
+export interface Outcome {
+    /** To append to the ledger. */
+    events: Event[];
+    notice: {
+        text: string;
+        tone: Tone;
+    };
+}
+/** What a widening never covers, in words — the three `family.outside` holds back. */
+export declare const EXCEPT = "except dangerous ones, ones that write a file and ones that run another program";
+export declare const NOT_COVERED = "dangerous ones, and any that write a file or run another program";
+/** What `x` is called on a target: revoke what answers, forget what is only counting. */
+export declare function revokeLabel(target: Target): {
+    label: string;
+    off: boolean;
+};
+/**
+ * `x`. A command loses its standing for every agent. A family loses every command in it and its
+ * widenings. An answer in the feed stops what gave it: the rule's own count, or the widening.
+ * OpenCode's own "always" is OpenCode's: Trust cannot take it back, and says so.
+ */
+export declare function revoke(target: Target, reading: Reading, at: number): Outcome;
+/** The family `w` acts on, and for which agent. */
+export interface WidenScope {
+    permission: string;
+    family: string;
+    /** The agent `w` would widen it for. */
+    agent?: string;
+    /** Agents it is widened for now, of those `w` would act on: non-empty means `w` undoes. */
+    undo: string[];
+}
+export declare function widenScope(target: Target, families: readonly Family[]): WidenScope | undefined;
+/** The family's name in a button: commands stay lowercase, where it runs is left to the card. */
+export declare function familyLabel(permission: string, family: string): string;
+/** What `w` is called: `Trust any head`, `Undo any head`, or dimmed when the family never widens. */
+export declare function widenLabel(scope: WidenScope | undefined, named?: boolean): {
+    label: string;
+    off: boolean;
+};
+/**
+ * `w`: trust a whole family for one agent, or take that back. Never automatic — this is the only place
+ * a `widened` event is made, and only a person reaches it. A dangerous family is refused, with why.
+ */
+export declare function widen(scope: WidenScope | undefined, families: readonly Family[], at: number): Outcome;
+/**
+ * The target as `opencode.json` would say it, for you to paste — Trust never writes OpenCode's
+ * config. A family is a wildcard (`"ls *": "allow"`), and config says less than a widening: not which
+ * agent, and not the commands a widening still asks about.
+ */
+export declare function configSnippet(target: Target): {
+    text: string;
+    note?: string;
+};

package/types/core/view/activity.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The screen `/trust` opens on: what Trust did for you, newest first, then what it is about to do.
+ *
+ *    Trust · opencode-cockpit                                                   ● answering
+ *
+ *    TODAY  Trust answered 4 prompts for you                       ▁▁▃▁▅▂█  last 7 days
+ *   ▌09:41  ✓ git status --short       build     trusted since yesterday, 3 in a row
+ *    09:40  ✓ ls -la                   general   in a family you widened: ls
+ *
+ *    ALMOST THERE  one more approval and Trust answers these
+ *     ○ bun --version                  build     ▰▰▱       2 of 3
+ *     ○ git push origin feat/trust     build     ▰▰▰▰▰▱▱▱  5 of 8   dangerous
+ *
+ *    ! WATCH OUT   OpenCode's own "always" approves more than it looks, until it restarts
+ *     ! find *  sed *                  general   [enter] what it covers
+ *
+ *    RULES  11 trusted · 14 learning · 101 seen once                      l  Open the ledger
+ *
+ *    [enter] Why   [x] Revoke   [w] Trust Family   [l] Ledger   [p] Pause   [?] Keys   [esc] Close
+ *
+ * Transparency is the point of Trust, so it leads with it: the question a person opens it with is
+ * "what did it do while I was not looking?", and the first line answers it. What is close comes
+ * next, because that is what will happen next; OpenCode's own broad approvals get a band of their
+ * own, so they cannot be mistaken for Trust's rules; and managing rules is one key away, in the
+ * ledger (explorer.ts). Every list is a window that follows the cursor, so a short dialog still
+ * reaches everything.
+ */
+import { type Answer, type History } from "../history.ts";
+import { type Target } from "./actions.ts";
+import { type AlwaysGroup, type Command, type Counts, type Family, type Reading } from "./model.ts";
+import { type Hit, type KeyLine } from "./parts.ts";
+import { type Row, type Run } from "./rows.ts";
+export type ActivityItem = 
+/** An answer Trust gave; `count` answers of the same line in a row are one item. */
+{
+    kind: "answer";
+    key: string;
+    answer: Answer;
+    count: number;
+} | {
+    kind: "almost";
+    key: string;
+    command: Command;
+} | {
+    kind: "always";
+    key: string;
+    group: AlwaysGroup;
+};
+export interface ActivityModel {
+    /** Every item the cursor moves over, in screen order. */
+    items: ActivityItem[];
+    feed: ActivityItem[];
+    almost: ActivityItem[];
+    always: ActivityItem[];
+    /** Answers today; when there are none, the feed is the latest from earlier days. */
+    today: number;
+    week: number[];
+    counts: Counts;
+    commands: Command[];
+    families: Family[];
+}
+export declare function activityModel(input: Reading & {
+    history: History;
+}): ActivityModel;
+/** What the cursor's item is, for `x`, `w` and `c`. */
+export declare function targetOf(item: ActivityItem, model: ActivityModel): Target;
+/**
+ * Why Trust answered, in a few muted words: the approvals that earned it and when, or the family you
+ * widened. Read from the rule's own moments (history.ts); when the window no longer reaches back that
+ * far, the reason the answering window logged.
+ */
+export declare function answerWhy(answer: Answer, reading: Reading & {
+    history: History;
+}): string;
+export interface ActivityInput extends Reading {
+    width: number;
+    height: number;
+    history: History;
+    /** The project's folder name, for the header. */
+    project: string;
+    /** The key of the item under the cursor; the first item when it is not there. */
+    selected?: string;
+    notice?: {
+        text: string;
+        tone: Run["tone"];
+    };
+    /** `?`: every key, in the body's place. */
+    keys?: boolean;
+}
+export interface ActivityView {
+    rows: Row[];
+    /** The item under the cursor, as drawn: the caller's actions act on it. */
+    item?: ActivityItem;
+    model: ActivityModel;
+    /** Where a click lands: a row selects, the ledger button opens the ledger. */
+    hits: Hit[];
+}
+/** The shortest dialog drawn: a header, a little of each list, the rules line and a way out. */
+export declare const MIN_HEIGHT = 11;
+export declare const ACTIVITY_KEYS: readonly KeyLine[];
+export declare function activityRows(input: ActivityInput): ActivityView;

package/types/core/view/explorer.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The ledger, behind `l`: every rule Trust holds, as a tree of families, and a card that explains the
+ * one selected — always on screen, so there is no details key to find.
+ *
+ *    Trust · opencode-cockpit             11 trusted · 14 learning · 101 seen once   ● answering
+ *   ────────────────────────────────────────┬─────────────────────────────────────────────────────
+ *    FAMILIES                      / filter │  head -30
+ *    ▾ head           1 ✓  5 ○              │  ✓ Trusted for  general  · ready, not used yet
+ *   ▌    head -30          ✓ trusted        │
+ *        head -40          ▰▰▱ 2 of 3       │  Exactly     head -30
+ *        + 3 more                           │  Still asks  head -31 · head -30 > out.txt
+ *    ▸ git status     1 ✓  1 ○              │  History     ✓ 9h  ✓ 9h  ✓ 9h  → trusted
+ *      ls -la              ✓ trusted 1×     │              3 approvals in a row, all yours
+ *      git push …      !  ▰▰▰▰▰▱▱▱ 5 of 8   │  Family      head · 6 commands, 1 trusted
+ *    ! OpenCode always    2 broad rules     │   x  Revoke    w  Trust any head    c  Copy rule
+ *   ────────────────────────────────────────┴─────────────────────────────────────────────────────
+ *    [↑/↓] Move   [←/→] Fold   [tab] Card   [/] Filter   [p] Pause   [?] Keys   [esc] Back
+ *
+ * **A command is one row.** The list it replaced split a family into what answers and what learns, so
+ * `head -30` was in one section while `head` was in the other, and the details repeated. Here a family
+ * is one fold, like a folder in an editor, and a command one row in it whatever its agents say; the
+ * card lists each agent's standing.
+ *
+ * **The card is the explanation.** The command whole, on a raised panel; where each agent stands; the
+ * exact text and what still asks; the approvals that earned it (history.ts); its family and what `w`
+ * would do; and the actions as buttons you can click or reach with `tab`.
+ *
+ * Below about ninety columns the card moves under the tree, the selection kept in view above it.
+ */
+import { type History, type Mark } from "../history.ts";
+import { type Target } from "./actions.ts";
+import { type AlwaysGroup, type Command, type Counts, type Family, type Reading } from "./model.ts";
+import { type Hit, type KeyLine } from "./parts.ts";
+import { type Row, type Run, type Tone } from "./rows.ts";
+export type Node = {
+    kind: "family";
+    key: string;
+    family: Family;
+    open: boolean;
+} | {
+    kind: "command";
+    key: string;
+    command: Command;
+    family: Family;
+    nested: boolean;
+}
+/** The folded tail of an open family: `+ 3 more`. */
+ | {
+    kind: "more";
+    key: string;
+    family: Family;
+    hidden: number;
+} | {
+    kind: "always";
+    key: string;
+    groups: AlwaysGroup[];
+};
+export interface Tree {
+    /** Families opened, by `Family.key`. */
+    open: ReadonlySet<string>;
+    /** Families whose tail is shown too, by `Family.key`. */
+    full: ReadonlySet<string>;
+    /** Only what matches this text, every family with a match open. Empty: everything. */
+    filter: string;
+}
+export interface ExplorerModel {
+    nodes: Node[];
+    families: Family[];
+    commands: Command[];
+    counts: Counts;
+}
+/** Commands an open family lists before folding the rest into `+ N more`. */
+export declare const TAIL = 3;
+export declare const familyNodeKey: (family: Family) => string;
+export declare const commandNodeKey: (command: Command) => string;
+export declare const ALWAYS_KEY = "o:always";
+export declare function explorerModel(input: Reading & Tree): ExplorerModel;
+/** What `x`, `w` and `c` act on, for a node. */
+export declare function nodeTarget(node: Node): Target;
+/** The tree state that shows `command` with its family open, its tail too when it is folded there. */
+export declare function reveal(tree: {
+    open: Set<string>;
+    full: Set<string>;
+}, families: readonly Family[], subject: {
+    permission: string;
+    subject: string;
+}): string | undefined;
+/** One labelled fact on the card: each line wraps on its own. `keep`: higher stays when room is short. */
+interface Fact {
+    label: string;
+    lines: Run[][];
+    keep: number;
+    /** The first line is a row of moments: it keeps its newest end on one row rather than wrapping. */
+    newest?: boolean;
+}
+export interface Button {
+    key: string;
+    label: string;
+    off: boolean;
+    action: "revoke" | "widen" | "copy";
+}
+interface CardParts {
+    title: Run[];
+    standing: Run[][];
+    facts: Fact[];
+    buttons: Button[];
+}
+export interface CardReading extends Reading {
+    history: History;
+    families: readonly Family[];
+}
+/** The buttons a node offers: `x`, `w` where a family can widen, `c`. */
+export declare function buttonsOf(node: Node, families: readonly Family[]): Button[];
+/**
+ * The moments that made a rule what it is, oldest to newest, the newest kept when they do not all fit:
+ * `✓ 9h  ✓ 9h  ✓ 9h  → trusted  answered 4×`.
+ */
+export declare function historyRuns(marks: readonly Mark[], need: number, expireMs: number, now: number): Run[];
+export declare function cardOf(node: Node, reading: CardReading): CardParts;
+export interface ExplorerInput extends Reading, Tree {
+    width: number;
+    height: number;
+    history: History;
+    project: string;
+    /** The node under the cursor, by key; the first node when it is not there. */
+    selected?: string;
+    /** `tab` moved into the card: which button is focused. */
+    focus?: {
+        button: number;
+    };
+    /** `/` was pressed: what has been typed so far. */
+    typing?: string;
+    notice?: {
+        text: string;
+        tone: Tone;
+    };
+    /** `?`: every key, in the body's place. */
+    keys?: boolean;
+}
+export interface ExplorerView {
+    rows: Row[];
+    node?: Node;
+    model: ExplorerModel;
+    buttons: Button[];
+    hits: Hit[];
+    /** Whether the card is beside the tree (true) or under it. */
+    wide: boolean;
+}
+/** At this width and wider the card is beside the tree; narrower, under it. */
+export declare const WIDE = 90;
+export declare const MIN_HEIGHT = 11;
+export declare const EXPLORER_KEYS: readonly KeyLine[];
+export declare function explorerRows(input: ExplorerInput): ExplorerView;
+export {};

package/types/core/view/model.d.ts

@@ -0,0 +1,106 @@
+/**
+ * What both Trust screens read: every command Trust has counted, once, with where each agent stands
+ * on it; the families they group into; and the three numbers that sum a project up.
+ *
+ * **One command, one place.** The ledger used to split a family by section, so `head -30` was under
+ * Answers while `head` was also under Learning and its details repeated. Here a command is one
+ * `Command` whatever its agents say about it — trusted for one, two of three for another — and a
+ * family one `Family`. The screens draw each once.
+ */
+import { type Always, type Entry, type State, type Thresholds, type Widened } from "../ledger.ts";
+export interface Reading {
+    state: State;
+    settings: Thresholds;
+    now: number;
+}
+/** Where one agent stands on one command. */
+export type Stand = {
+    kind: "trusted";
+}
+/** Not trusted by its own count, answered through a family you widened. */
+ | {
+    kind: "widened";
+    family: string;
+} | {
+    kind: "counting";
+    have: number;
+    need: number;
+    expired: boolean;
+};
+export declare function standOf(entry: Entry, { state, settings, now }: Reading): Stand;
+export declare const answers: (stand: Stand) => boolean;
+/** Approvals still needed; an expired count is as far as it gets. Zero: it answers. */
+export declare const distance: (stand: Stand) => number;
+/** One agent's standing on a command. */
+export interface Standing {
+    entry: Entry;
+    stand: Stand;
+}
+/**
+ * Where a command is, all agents together:
+ * - `answering`: Trust answers it for at least one agent;
+ * - `learning`: counting, with approvals that matter (two in a row, or answered before);
+ * - `once`: approved once and never again — most never come back, so they are kept out of the way.
+ */
+export type Phase = "answering" | "learning" | "once";
+export interface Command {
+    /** `[permission, subject]`, the same for every agent. */
+    key: string;
+    permission: string;
+    subject: string;
+    family: string;
+    /** Every agent's standing, the one that answers first, then the closest to it. */
+    standings: Standing[];
+    phase: Phase;
+    /** Today's reading of why it costs more, as of the last time it was asked. */
+    danger?: string;
+    /** The last approval or answer, any agent. */
+    lastAt: number;
+}
+export declare const commandKey: (permission: string, subject: string) => string;
+/** The standing the command is drawn by: the one that answers, else the closest. */
+export declare const leadOf: (command: Command) => Standing;
+/** Approvals the closest agent still needs. */
+export declare const closeness: (command: Command) => number;
+/**
+ * Every command anyone approved or Trust answered, one each. A subject only ever rejected has
+ * nothing to show and is left out.
+ */
+export declare function commandsOf(reading: Reading): Command[];
+/** Answering newest first; then learning closest first, a dangerous one after the rest; then once. */
+export declare function byPhase(a: Command, b: Command): number;
+export interface Family {
+    /** `[permission, family]`. */
+    key: string;
+    permission: string;
+    family: string;
+    /** Its commands, `byPhase`. */
+    commands: Command[];
+    /** The agents you trusted the whole family for. */
+    widened: Widened[];
+    lastAt: number;
+}
+export declare const familyKey: (permission: string, family: string) => string;
+/**
+ * The commands grouped by family, with every widened family — even one with no command left. Families
+ * that answer first (newest first), then those learning (closest first), the dangerous ones after,
+ * and families seen only once last.
+ */
+export declare function familiesOf(reading: Reading, commands?: readonly Command[]): Family[];
+/** The project in three numbers, one per command. */
+export interface Counts {
+    trusted: number;
+    learning: number;
+    once: number;
+}
+export declare function countsOf(commands: readonly Command[]): Counts;
+/** OpenCode's own "always" approvals, one group per agent and permission, the newest first. */
+export interface AlwaysGroup {
+    key: string;
+    permission: string;
+    agent: string;
+    patterns: string[];
+    at: number;
+    approvals: Always[];
+}
+export declare function alwaysGroups(state: State): AlwaysGroup[];

package/types/core/view/parts.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The pieces both Trust screens are built from: an agent's chip, a tinted badge, a button, a meter,
+ * the week's sparkline, the header and the key list.
+ *
+ * Colour came back to Trust as signal (docs/building/design-system.md): green is what answers, the
+ * warning what is close or needs a look, red what is dangerous. Each piece pairs its colour with a
+ * word or a shape — a meter beside `2 of 3`, a badge that says `dangerous` — so none of it is read
+ * by colour alone.
+ */
+import { type Hint } from "@opencode-cockpit/client/design";
+import { type Row, type Run } from "./rows.ts";
+export declare const muted: (text: string) => Run;
+export declare const plain: (text: string) => Run;
+export declare const key: (name: string) => Run;
+/** An agent, as a chip: its name in the info tone on a faint fill of the same. */
+export declare const chip: (agent: string) => Run;
+/** A word on a tint of its tone: ` ● answering `, ` dangerous `. */
+export declare const badge: (text: string, tone: "success" | "warning" | "error") => Run;
+/**
+ * A button: its key, then what it does, on a raised fill — a run you can click as well as a key you
+ * can press. `on`: focused, drawn solid in the accent. `off`: nothing to act on here; dimmed rather
+ * than removed, because a button that comes and goes cannot be learned.
+ */
+export declare function button(name: string, label: string, state?: {
+    on?: boolean;
+    off?: boolean;
+}): Run[];
+/** How close: one `▰` per approval that counts, `▱` for each still to go. Dangerous ones in red. */
+export declare function meter(have: number, need: number, danger: boolean): Run[];
+/** A day per cell, scaled to the busiest: a day with none is the empty track, in the border tone. */
+export declare function sparkline(counts: readonly number[]): Run[];
+/** `9h`, `2d`, `now`: a time in a column of times, where `ago` on every one says nothing. */
+export declare const since: (ms: number) => string;
+/** `just now`, `15m ago`. */
+export declare const when: (ms: number) => string;
+export declare const plural: (count: number, one: string, many?: string) => string;
+export declare const agentsText: (agents: readonly string[]) => string;
+/** `09:41` today; `Tue 09:41` this week; `Sep 21` before that. Local time, as a clock on the wall. */
+export declare function clock(at: number, now: number): string;
+/** `today`, `yesterday`, `on Tue`, `on Sep 21`: when, as a day. */
+export declare function dayWord(at: number, now: number): string;
+/**
+ * `Trust · project` on the left; on the right whatever the screen adds, then whether Trust is
+ * answering — the first thing to know, so it is a badge: `● answering`, or `○ paused`.
+ */
+export declare function headerRow(project: string, paused: boolean, extra: Run[], width: number): Row;
+/** The keys row: a cell of margin at each end, the way out last and never dropped. */
+export declare function footerRow(hints: readonly Hint[], width: number): Row;
+export interface KeyLine {
+    keys: string[];
+    does: string;
+}
+/** `runs` wrapped at spaces into rows of `width`, at most `max`; the last says `…` when cut. */
+export declare function wrapRuns(runs: readonly Run[], width: number, max?: number): Row[];
+/** Every key a screen takes, one line each, what each does wrapped under its column rather than cut. */
+export declare function keyListRows(list: readonly KeyLine[], width: number): Row[][];
+/** As many key lines as fit in `room` rows; a list cut short says how many keys are below. */
+export declare function keyListBody(list: readonly KeyLine[], width: number, room: number): Row[];
+/** Something on screen a click acts on: a row to select, or a button to press. */
+export type Hit = 
+/** `x0`/`x1`: the columns it covers, when it does not take the whole row. */
+{
+    kind: "row";
+    y: number;
+    key: string;
+    x0?: number;
+    x1?: number;
+} | {
+    kind: "button";
+    y: number;
+    x0: number;
+    x1: number;
+    action: string;
+};
+/** The buttons in a row of runs, by where each starts and ends. `actions`: one per button, in order. */
+export declare function buttonHits(row: Row, y: number, actions: readonly string[]): Hit[];