toolroll 0.9.53 → 0.9.55

package/dist/server/render-pages.d.ts

@@ -0,0 +1,535 @@
+/** Everyday console pages: home, inbox, board, work, projects, fleet and the queue. */
+import { type Html } from "../html.js";
+import { type AssignmentSnapshot } from "../assignment.js";
+import { type BoardCard } from "../board.js";
+import { type BrowserLimits } from "../browser-workspace.js";
+import { type CheckLevel } from "../check-levels.js";
+import { type DispatchDiagnosis } from "../dispatch.js";
+import { type FirstRunStep } from "../first-run.js";
+import { type Gap } from "../gaps.js";
+import { type ListOutcome } from "../onboard.js";
+import { type parseBaseTreeSnapshot } from "../peek.js";
+import { type CriterionMatrixRow } from "../proof.js";
+import { type QualityMode } from "../quality.js";
+import { type Runner } from "../runner.js";
+import { type Scope, type UnattendedPermissionMode } from "../scope.js";
+import { type Decision, type Incident, type RepairChainRow, type Run, type Store, type Task, type TaskState, type WorktreeRow } from "../store.js";
+import { tally } from "../summary.js";
+import { type WorkIndexGroup, type WorkIndexPage } from "../work-index.js";
+import { type WorkFacts, type WorkStatus, type WorkView } from "../workspace-ui.js";
+import { type Chrome, type Screen } from "./chrome.js";
+import { type PlanContractView, type RouteView } from "./render-tasks.js";
+export declare const TASK_STATES: readonly TaskState[];
+/**
+ * The inbox (v3): only things stalling progress without a person, one card
+ * per underlying stall, each with its verb inline or one step away. No
+ * auto-refresh — approval links lead to the step-up screen, and a page
+ * that might hold typed input never re-renders itself.
+ */
+export type InboxTab = "needs-you" | "ready" | "running" | "all";
+export declare const INBOX_TABS: readonly {
+    id: InboxTab;
+    label: string;
+}[];
+export declare function parseInboxTab(raw: string | null): InboxTab | undefined;
+/** What each tab holds, as a short fingerprint: a tab is unread when its
+ * fingerprint differs from the one this browser saw there last. */
+export declare function inboxFingerprints(data: Pick<Parameters<typeof inboxPage>[1], "decisions" | "approvals" | "requeueables" | "cancelledBlockers" | "gaps" | "needsVerification" | "ready" | "running">): Record<InboxTab, string>;
+export declare function inboxPage(chrome: Chrome, data: {
+    csrf: string;
+    revision: number;
+    /** No project open in scoped mode: every admitted project at once,
+     * chips on every row, links only — acting means opening the project. */
+    rollup: boolean;
+    /** A project is OPEN: only then do decisions answer on the card. The
+     * legacy unscoped projectless inbox stays links-only too (commit-1
+     * review, finding 4) — the partial belongs to a chosen project. */
+    interactive: boolean;
+    decisions: (Decision & {
+        taskId: string;
+        repo?: string | null;
+    })[];
+    approvals: {
+        taskId: string;
+        title: string;
+        goal: string;
+        proposedAt: string;
+        repo?: string | null; /** v48 authority repair: the closed consent door's title, or null when a yes could bind. */
+        closed?: string | null;
+    }[];
+    requeueables: {
+        taskId: string;
+        title: string;
+        state: TaskState;
+        strikes: number;
+        incidentCount: number;
+        repo?: string | null;
+    }[];
+    cancelledBlockers: {
+        blockerId: string;
+        dependentCount: number;
+        exampleDependent: string;
+        repo?: string | null;
+        blockerRepo?: string | null;
+    }[];
+    gaps: Gap[];
+    /** A completed task whose proof is short or refuted and not yet accepted
+     * (Priority 2) — reads "needs verification" here too, never silently
+     * "done" just because the inbox does not otherwise look at finished work. */
+    needsVerification: {
+        taskId: string;
+        title: string;
+        verdict: "short" | "refuted";
+        repo?: string | null;
+        matrix?: CriterionMatrixRow[];
+        repairChain?: RepairChainRow | null;
+    }[];
+    /** The first-run steps; null once the installation has had its first Ready result. */
+    wizard: FirstRunStep[] | null;
+    /** Whether any worker is answering right now — said at the top when none is. */
+    worker: {
+        answering: number;
+        registered: number;
+        lastHeard: string | null;
+    };
+    now: Date;
+    /** Console v2: the tab shown, results ready to review, work running now,
+     * and the tabs holding something this browser hasn't seen (dots on a phone). */
+    tab?: InboxTab;
+    ready?: {
+        taskId: string;
+        title: string;
+        detail: string;
+        repo: string | null;
+    }[];
+    running?: {
+        taskId: string;
+        title: string;
+        detail: string;
+        repo: string | null;
+    }[];
+    unread?: readonly InboxTab[];
+}): Screen;
+/** System: the machinery — workers, background service, workspaces. */
+export declare function systemPage(chrome: Chrome, data: {
+    agents: {
+        phase: "plan" | "build" | "repair" | "review";
+        provider?: string;
+        model?: string | null;
+        source?: "pinned" | "flag" | "project" | "installation" | "default";
+        problem?: string;
+        setBy: string | null;
+    }[];
+    building: {
+        taskId: string;
+        runner: string;
+        claimedAt: string;
+        expiresAt: string;
+        model: string | null;
+    }[];
+    runners: Runner[];
+    worktrees: WorktreeRow[];
+    episode: {
+        id: number;
+        startedAt: string;
+        endedAt: string | null;
+        ticks: number;
+        built: number;
+        broke: number;
+    } | null;
+    outboxPending: number;
+    externalWork?: {
+        remoteRepo: string;
+        blocked: string | null;
+        openEpisode: string | null;
+    }[];
+    now: Date;
+}): Screen;
+/**
+ * The board: the pipeline as lanes, position as meaning — attention, then
+ * queued, then waiting, then building, then recently done. Read-only by
+ * construction (every card is a link, no forms, no nonces), which is what
+ * makes it safe to re-render itself while somebody watches.
+ */
+export declare function boardBody(data: {
+    cards: BoardCard[];
+    done: ReturnType<Store["listCompletedWorkScoped"]>;
+    saturated: boolean;
+    now: Date;
+    /** The rolled-up view: every project inside the ceiling at once. */
+    all: boolean;
+    project: string | null;
+    delta: {
+        agoMinutes: number;
+        built: number;
+        failed: number;
+        questions: number;
+    } | null;
+}, ciRed: (pr: number) => boolean): Html;
+/** Completed work: one row per done task, its final run and PR attached. */
+export declare function donePage(chrome: Chrome, rows: ReturnType<Store["listCompletedWorkScoped"]>, ciRed: (pr: number) => boolean): Screen;
+export declare function homePage(chrome: Chrome, data: {
+    csrf: string;
+    taskCount: number;
+    repo: string | null;
+    building: {
+        taskId: string;
+        runner: string;
+        claimedAt: string;
+        expiresAt: string;
+        model: string | null;
+    }[];
+    runners: Runner[];
+    worktrees: WorktreeRow[];
+    episode: {
+        id: number;
+        startedAt: string;
+        endedAt: string | null;
+        ticks: number;
+        built: number;
+        broke: number;
+    } | null;
+    summary: ReturnType<typeof tally<Run & {
+        taskId: string;
+    }>>;
+    decisions: (Decision & {
+        taskId: string;
+    })[];
+    incidents: (Incident & {
+        taskId: string;
+    })[];
+    stranded: {
+        id: string;
+        blockedBy: string[];
+    }[];
+    gaps: Gap[] | null;
+    outboxPending: number;
+    settings: boolean;
+    now: Date;
+}): Screen;
+export type TaskComposerPrefill = {
+    title: string;
+    goal: string;
+    not: string;
+    touches: string;
+    acceptance: string;
+    values?: URLSearchParams;
+};
+/** The one front door for new work. The common path is one prompt and one
+ * button; the detailed contract remains available in-place for templates,
+ * experts, and the rare task that should skip repository-aware planning. */
+/** Where new work goes when no project is open: a choice from the projects
+ * this person already has, never a typed path; a new project is one link
+ * away. Same-named checkouts show their parent folder to tell them apart. */
+export declare function projectPickerHtml(projects: {
+    path: string;
+    name: string;
+}[], chosen: string): Html;
+export declare function taskComposerHtml(data: {
+    project: string | null;
+    projectRevision?: number;
+    prefill?: TaskComposerPrefill | null;
+    candidates?: {
+        id: string;
+        title: string;
+    }[];
+    permissionDefault: UnattendedPermissionMode;
+    qualityDefault: QualityMode;
+    /** Projects this person may place work in, most recently opened first. */
+    projects?: {
+        path: string;
+        name: string;
+    }[];
+}): Html;
+export type WorkRow = WorkFacts & {
+    assignment?: AssignmentSnapshot | null;
+    assignmentProblem?: boolean;
+    executionId?: string;
+    familyNotice?: string | null;
+    status: WorkStatus;
+    resultRunId: number | null;
+};
+export declare const TASK_GROUP_LABEL: Readonly<Record<WorkIndexGroup, string>>;
+export declare function workPage(chrome: Chrome, data: {
+    view: WorkView;
+    projectFilter?: string;
+    work: WorkIndexPage;
+    previous: boolean;
+    multiProject: boolean;
+    now: Date;
+    limits?: BrowserLimits | null;
+}): Screen;
+export declare function tasksPage(chrome: Chrome, tasks: Task[], state: TaskState | null, problem: string | null, repo?: string | null, prefill?: TaskComposerPrefill | null, permissionDefault?: UnattendedPermissionMode, qualityDefault?: QualityMode, replaced?: ReadonlyMap<string, string>): Screen;
+export declare function browsePage(chrome: Chrome, data: {
+    at: string;
+    root: string;
+    roots: string[];
+    parent: string | null;
+    entries: {
+        name: string;
+        path: string;
+        git: boolean;
+    }[];
+    /** Unused: postForm adds the request's CSRF field. Kept for callers. */
+    csrf: string;
+}): Screen;
+/** The compact completed row shared by both halves of the control room. */
+export type WorkbenchDone = {
+    taskId: string;
+    title: string;
+    outcome: string | null;
+    repo: string | null;
+};
+/**
+ * The control-room rail (attended A1): every state that matters while a
+ * person supervises, ordered by intervention cost. The project chip is
+ * deliberately repeated on every row — a title is not a workspace, and
+ * switching context must never depend on remembering which repo is open.
+ */
+export declare function workbenchRail(data: {
+    attention: BoardCard[];
+    building: BoardCard[];
+    waiting: BoardCard[];
+    queued: BoardCard[];
+    done: WorkbenchDone[];
+    selected: string | null;
+    saturated: boolean;
+}): Html;
+/**
+ * The portfolio overview (arc slice 1a): what waits on you, what the last
+ * 24 hours of run starts amounted to, what is running, and the terminal-run
+ * ledger — all of it across every admitted project, a project chip on every
+ * row. The caller has already applied admission and per-row visibility.
+ */
+export declare function portfolioOverview(data: {
+    attention: BoardCard[];
+    building: BoardCard[];
+    waiting: BoardCard[];
+    queued: BoardCard[];
+    done: WorkbenchDone[];
+    saturated: boolean;
+    decisions: (Decision & {
+        taskId: string;
+        repo?: string | null;
+    })[];
+    approvals: {
+        taskId: string;
+        title: string;
+        goal: string;
+        proposedAt: string;
+        repo?: string | null; /** v48 authority repair: the closed consent door's title, or null when a yes could bind. */
+        closed?: string | null;
+    }[];
+    requeueables: {
+        taskId: string;
+        title: string;
+        state: TaskState;
+        strikes: number;
+        incidentCount: number;
+        repo?: string | null;
+    }[];
+    cancelledBlockers: {
+        blockerId: string;
+        dependentCount: number;
+        exampleDependent: string;
+        repo?: string | null;
+        blockerRepo?: string | null;
+    }[];
+    gaps: Gap[];
+    gapsProject: string | null;
+    runs24: (Run & {
+        taskId: string;
+    })[];
+    live: {
+        taskId: string;
+        runner: string;
+        claimedAt: string;
+        expiresAt: string;
+        model: string | null;
+        repo: string | null;
+    }[];
+    ledger: {
+        runId: number;
+        taskId: string;
+        title: string;
+        repo: string | null;
+        outcome: string;
+        role: string;
+        provider: string | null;
+        model: string | null;
+        startedAt: string;
+        ranMinutes: number | null;
+        costUsd: number | null;
+        authMode: "subscription" | "api-key" | null;
+        prNumber: number | null;
+        prUrl: string | null;
+    }[];
+    /** "" when there is no session token: then no form renders. postForm adds the field itself. */
+    csrf: string;
+    now: Date;
+}): Html;
+export type OnboardCardState = {
+    enabled: false;
+    why: string;
+} | {
+    enabled: true;
+    roots: readonly string[];
+    record: [string, {
+        nameWithOwner: string;
+        rootIndex: number;
+        target: string;
+        diskUsageKib: number | null;
+        large: boolean;
+        mintedAt: number;
+    }] | null;
+};
+export type ProjectPeek = {
+    waiting: number;
+    queued: number;
+    running: number;
+    doneRecently: number;
+};
+/**
+ * owner/name from a git remote URL — FULLY ANCHORED https/ssh github.com
+ * forms only (ghlist review, finding 2): a foreign host carrying
+ * "github.com" in its path, or a non-github host, must never read as a
+ * GitHub identity. Everything else is null.
+ */
+export declare function githubIdentityOf(remoteUrl: string): string | null;
+/**
+ * The `origin` remote's url from a repository's OWN .git/config. BOUNDED
+ * I/O by construction (ghlist review, finding 1): the final component may
+ * not be a symlink (O_NOFOLLOW + lstat), must be a REGULAR file under a
+ * size cap, and at most 64 KiB are ever read — a sparse monster or a fifo
+ * planted as a "config" reads as null, never as a hang. Parsed LINE BY
+ * LINE with real section tracking (finding 2): a `[remote "origin"]`
+ * embedded inside some other value never opens the section. null when
+ * unreadable or origin-less; a worktree-style `.git` FILE (gitdir pointer)
+ * reads null too, which is honest — its identity lives elsewhere. The
+ * answer is ADVISORY metadata for offering a button: the /projects/open
+ * road re-proves path, ceiling, and git-ness before anything mutates, and
+ * a config that lies about its origin can only mislabel a repository the
+ * operator was already allowed to open.
+ */
+export declare function originUrlOf(repoPath: string): string | null;
+/** The GitHub listing page: the account's repositories with ONE honest
+ * action each. Names, descriptions, and paths are gh/filesystem DATA —
+ * escaped at the sink like everything else. */
+export declare function githubReposPage(chrome: Chrome, data: {
+    listed: ListOutcome;
+    local: Map<string, string>;
+    registered: Set<string>;
+    /** Unused: postForm adds the request's CSRF field. Kept for callers. */
+    csrf: string;
+    cloneReady: boolean;
+    openProject: string | null;
+}): Screen;
+export declare function projectsPage(chrome: Chrome, recent: {
+    path: string;
+    name: string;
+    lastOpenedAt: string;
+}[], candidates: string[], open: string | null, problem: string | null, _unscopedMode: boolean, browsable?: boolean, onboard?: OnboardCardState | null, peeks?: Record<string, ProjectPeek | null>, returnTo?: string, pullRequestsOn?: (path: string) => boolean, checkLevelOf?: (path: string) => CheckLevel): Screen;
+/** The no-script "move to the front" sentinel: the form cannot name the
+ * front of a partition, so the handler resolves it (slice 1b, fix 1). */
+export declare const QUEUE_FRONT = "__TOP__";
+export type QueueCardTask = ReturnType<Store["queueScoped"]>[number] & {
+    dispatch?: DispatchDiagnosis | null;
+};
+export declare function queueCard(one: QueueCardTask, revision: number, queueRevision: number, workers: {
+    name: string;
+    retired: boolean;
+}[], column: string): Html;
+/** The queue columns fragment — shared queue first, then each worker. */
+export declare function queueBody(tasks: QueueCardTask[], workers: {
+    name: string;
+    retired: boolean;
+    note: string | null;
+    capacity: number;
+    building: number;
+}[], revision: number, queueRevision: number): Html;
+/**
+ * The fleet screen — one lane per runner, and the work in front of it.
+ * Building claims pin to the top of their worker's lane (live — never
+ * draggable); queued reservations sit below it (draggable to another
+ * worker, re-reserving them). Every card wears its project chip, which is
+ * the whole point: which agent is on which project is the page's answer.
+ * Form-free like the board, except the per-worker note, so the lane stack
+ * can re-render itself while somebody watches.
+ */
+export declare function fleetBody(queued: ReturnType<Store["fleetQueue"]>, building: ReturnType<Store["liveClaims"]>, runners: Runner[], queueRevision: number, visibleRepo: (repo: string | null) => boolean): Html;
+/** Identical drag mechanics to the queue — the pointer events land on the worker's column. */
+export declare function fleetScript(): string;
+/** The /queue page's one nonce'd script: delegated pointer-event drag (it
+ * survives every fragment swap — finding 17) plus a poller that re-checks
+ * focus, dirty inputs, and an in-flight drag AT SWAP TIME, never only
+ * before the fetch. Select dirtiness compares against data-initial
+ * (finding 18); missing that, a select counts clean.
+ */
+export declare function queueScript(): string;
+export declare function newTaskPage(chrome: Chrome, project: string | null, projectRevision: number, problem: string | null, candidates?: {
+    id: string;
+    title: string;
+}[], permissionDefault?: UnattendedPermissionMode, qualityDefault?: QualityMode, projects?: {
+    path: string;
+    name: string;
+}[]): Screen;
+/**
+ * The triage flow: everything waiting on a person, one card at a time.
+ * Full context ON the card, the act inline, and every act lands back here
+ * — clearing the queue is taps, not navigation. Read state travels in the
+ * URL (the bounded skip cursor), never in the session: two tabs cannot
+ * fight, and a shared link shows the same queue.
+ */
+export declare function nextPage(chrome: Chrome, data: {
+    item: {
+        key: string;
+        kind: "decision";
+        decision: Decision & {
+            taskId: string;
+        };
+    } | {
+        key: string;
+        kind: "approval";
+        approval: {
+            taskId: string;
+            title: string;
+            goal: string;
+            digest: string;
+            proposedAt: string;
+        };
+    } | {
+        key: string;
+        kind: "requeue";
+        stalled: {
+            taskId: string;
+            title: string;
+            strikes: number;
+            incidentCount: number;
+        };
+    } | {
+        key: string;
+        kind: "gap";
+        gap: Gap;
+    } | null;
+    scope: Scope | null;
+    planDocument: string | null;
+    planContract?: PlanContractView | null;
+    approvalDigest: string | null;
+    /** v34: said inside the ceremony when the yes buys a report, not a branch. */
+    deliverable?: "branch" | "report";
+    /** v48: the agents the yes freezes — the one block every ceremony shows. */
+    route: RouteView | null;
+    csrf: string;
+    nonce: string;
+    remaining: number;
+    skipped: string[];
+    now: Date;
+}): Screen;
+export type PeekAdmission = {
+    run: Run;
+    /** The run's checkout, PROVEN non-null by the guards: a reviewer run
+     * (v29, artifact-only) is refused before admission ever forms. */
+    worktree: string;
+    epoch: string;
+    entries: ReturnType<typeof parseBaseTreeSnapshot>;
+};