toolroll 0.5.0

package/dist/serve.d.ts

@@ -0,0 +1,313 @@
+import { CodingWorkspace } from './coding-workspace.js';
+import { type MailSender } from "./flow-actions.js";
+import { type TriggerIo } from "./flow-triggers.js";
+import { type AssignmentSnapshot } from './assignment.js';
+import { type VersionRunner } from "./model-catalog.js";
+import { type Server } from "node:http";
+import { type ProofVerdict, type CriterionMatrixRow } from "./proof.js";
+import { type Run, type Store } from "./store.js";
+import { previewGithubRepo, cloneGithubRepo, listGithubRepos } from "./onboard.js";
+import { run as execRun } from "./exec.js";
+import { type AgentChoice } from "./agentconfig.js";
+import { type RouteProjection, type RouteOverride, type RouteStamp, type RiskLevel } from "./phase-routing.js";
+import { type Phase } from "./provider.js";
+import type { RevisionLineage } from "./store.js";
+import type { SubscriptionMateRunner } from "./subscription-chat.js";
+export type ServeOptions = {
+    /** Native coding workspace injection for isolated integration tests. */
+    codingWorkspace?: CodingWorkspace;
+    store: Store;
+    evidenceRoot: string;
+    clock?: () => Date;
+    /**
+     * The console's canonical https origin, when TLS terminates in front
+     * (arc 3 finding 2/16): EXACTLY an origin — no path, query, credentials.
+     * The one trust anchor for secure-context features: it joins the allowed
+     * hosts, its origin authorizes POSTs, cookies turn Secure, and the
+     * install/push cards light up. X-Forwarded-* is never consulted.
+     */
+    publicUrl?: string;
+    /** Where repos.json lives — every enrollment locks exactly this file. */
+    registryPath?: string;
+    /** This console fronts an `up` process: onboarding copy says how to watch. */
+    upConsole?: boolean;
+    /** Extra Host values this server answers as (a Tailscale name, a LAN ip:port). */
+    allowedHosts?: readonly string[];
+    /**
+     * The first-account road (setup review): while NO approver exists, the
+     * login page offers "create the first account", gated by this code —
+     * printed once by the process that started the server, never stored.
+     * Five wrong codes close the road until the server restarts. The moment
+     * an approver exists, the page is the ordinary sign-in.
+     */
+    setupCode?: string;
+    /**
+     * Where the Telegram bot token lives when set from here. Present = the
+     * settings card renders; absent = no settings surface at all.
+     */
+    telegramTokenFile?: string;
+    /** Where messaging config files live (beside the database) — enables the
+     * primary-messenger selector on the settings screen. */
+    configDir?: string;
+    /** Test seam for the Slack setup handshake. */
+    slackFetcher?: typeof fetch;
+    discordFetcher?: typeof fetch;
+    /** Injected by tests: Microsoft sign-in, key metadata and Teams conversation calls. */
+    teamsFetcher?: typeof fetch;
+    /** Injected by tests: how "Check now" reaches GitHub (gh) and Linear (fetch). */
+    flowTriggerIo?: Partial<TriggerIo>;
+    /**
+     * The repo this console serves. Scopes run evidence to that repo's tasks
+     * (and unplaced ones) and turns on the gaps and capabilities views —
+     * without it those pages say so instead of guessing.
+     */
+    repo?: string;
+    /**
+     * The full authorization ceiling (v2 review, finding 1): `repos` this
+     * server may show and operate on, plus `projectRoots` under which any git
+     * repository qualifies. `repo` above is sugar for one entry in `repos`.
+     * No configuration at all is the legacy unscoped mode — everything
+     * visible, and stated as such where the code decides.
+     */
+    repos?: readonly string[];
+    projectRoots?: readonly string[];
+    /** Repositories the co-located `up` process has proved and is watching.
+     * Kept as a callback so projects added after startup appear immediately
+     * without turning the durable registry itself into an authorization source. */
+    currentRepos?: () => readonly string[];
+    /** Injected by tests: the fetch direct-API chat turns use, and where chat
+     * keys are read from (defaults to process.env). */
+    chatFetcher?: typeof fetch;
+    /** Subscription-backed mate transport; injected in tests so no real
+     * Codex or Claude membership turn is consumed. */
+    subscriptionChatRunner?: SubscriptionMateRunner;
+    /** Tests: stands in for `codex mcp list --json` in the project (the Tools page's "Found on this computer"). */
+    codexToolList?: (cwd: string) => Promise<string | null>;
+    /** Tests: the home whose ~/.toolroll (or older ~/.standing-orders) tool-secrets and ~/.claude.json the Tools page uses. */
+    toolHome?: string;
+    /** v87: sends Send email steps' mail and the settings test (tests inject one). */
+    mailSender?: MailSender;
+    /** v89: Google's token endpoint (tests inject a scripted one). */
+    googleFetch?: typeof fetch;
+    /** Tests: every request a one-click connection makes (discovery, registration, tokens). */
+    connectFetch?: typeof fetch;
+    /** Tests: every request sign-in with the identity provider makes (discovery, keys, tokens). */
+    ssoFetch?: typeof fetch;
+    chatEnv?: Record<string, string | undefined>;
+    /**
+     * The live peek's locality ASSERTION (live-peek v3 §3): the administrator
+     * who starts serve names the runner this machine owns. This is documented
+     * as an assertion, not machine-bound credential enforcement — the product
+     * has none anywhere. Absent = the peek is off, and says so.
+     */
+    desktopIdentity?: string;
+    /** Trusted native admission callback; enrollment rows alone never supply this authority. */
+    additionalProjectRepos?: () => readonly string[];
+    connectionProbe?: typeof execRun;
+    connectionHome?: string;
+    modelCatalogFetcher?: typeof fetch;
+    /** Test seams for Settings → Models: CLI version probes and the PATH they search. */
+    modelRunner?: VersionRunner;
+    modelPath?: string;
+    localRunner?: string;
+    /** The checkout pool root the peek confines itself to (realpath-proved). */
+    poolRoot?: string;
+    /**
+     * Editor deep links (arc 6): a DEPLOYMENT capability, not an activation.
+     * vscode:// links open on the BROWSER's machine, so links render only
+     * when three statements align: the operator started serve with
+     * --editor vscode AND --runner (this machine owns the worktrees), the
+     * run belongs to that runner, and THIS session turned links on for
+     * this device. "vscode" is the only value; the scheme is never data.
+     */
+    editorLinks?: "vscode";
+    /**
+     * The attended-mint capability (Phase 2E): present only on a co-located
+     * `up` console, which alone can hold a session. `headOf` reads the
+     * repository's CURRENT head — the exact commit the signed terms pin.
+     */
+    attended?: {
+        runner: string;
+        headOf: (repo: string) => Promise<string | null>;
+        coordinator?: import("./held.js").HeldSessionCoordinator;
+    };
+    /** Injected by tests: the onboarding ceremony's gh-facing halves — the
+     * ceremony's gating, nonce, and enrollment logic is what the HTTP tests
+     * prove; gh itself is proved by onboard.test.ts. */
+    ghPreview?: typeof previewGithubRepo;
+    ghClone?: typeof cloneGithubRepo;
+    ghList?: typeof listGithubRepos;
+};
+export declare function createDecisionServer(options: ServeOptions): Server;
+/**
+ * A vscode://file href, or null (arc 6, finding 2): the link exists only
+ * when every part is provably tame — an absolute, control-free worktree;
+ * a relative, single-line path whose segments contain no empty, dot,
+ * dot-dot, or backslash components (so lexical resolution stays below the
+ * worktree); a line inside the same 1..1,000,000 range the comment form
+ * enforces. Encoding failures return null — a file row degrades to plain
+ * text, never to a 500. The scheme is a constant, never data.
+ */
+export declare function editorFileHref(worktree: string, path: string, line?: number | null): string | null;
+/** The Agents view every console surface renders (v47): the SAME
+ * projection the CLI prints — who plans, builds, and revises,
+ * whether each was recommended, overridden, or pinned, its reasons, and
+ * the readiness the task's runners have reported (ready / unavailable /
+ * unknown — an unknown is said, never upgraded). Readiness is volatile and
+ * never part of what an approval signs, so the ceremony shows the agents
+ * and their reasons only. */
+export type RouteView = {
+    kind: "route" | "legacy" | "unreadable";
+    source: "approved" | "proposed" | "live" | null;
+    projection: RouteProjection | null;
+    /** A proven pre-routing row: its approved agent profile, nothing more. */
+    legacy: {
+        provider: string;
+        model: string;
+        repairModel: string;
+        approved: boolean;
+    } | null;
+    /** A routed row whose agents cannot be read — fail closed, in words. */
+    problem: string | null;
+    riskLevel: RiskLevel;
+    overrides: RouteOverride[];
+    /** An approver may edit: a live claim, a tournament, or a viewer session refuses. */
+    editable: boolean;
+    editableWhy: string | null;
+    /** A planner change after a draft landed asks for a real re-plan. */
+    replanOnPlanChange: boolean;
+    /** The scope digest the change forms CAS against; null = no scope yet. */
+    digest: string | null;
+    /** v48: the configured, role-valid agents an approver may choose from —
+     * every option an exact pair the operator named once in configuration.
+     * The form offers these and nothing else. */
+    choices: Record<Phase, AgentChoice[]>;
+};
+/**
+ * The sensitivity classifier (arc 4, findings 3/17): a body showing a
+ * password input renders WITHOUT the chrome additions (palette, overlay,
+ * global keys) — the page's own functional script still ships. Tolerant
+ * of quoting, casing, and whitespace; `data-type="password"` and prose
+ * mentioning passwords do not match. This is defense-in-depth over a
+ * file whose only HTML producer is its own double-quoted template
+ * convention — forceSensitive is the escape hatch for what a regex
+ * cannot judge.
+ */
+export declare const SENSITIVE_INPUT: RegExp;
+/**
+ * v100: for someone signed in with the identity provider, every step-up
+ * password field (autocomplete="current-password"; a secret like a bot token
+ * is never one) becomes that sign-in: confirmed, when the provider checked
+ * them in the last ten minutes, or a link to be checked again, then back here.
+ */
+export declare function ssoStepUps(html: string, sso: {
+    label: string;
+    fresh: boolean;
+}, returnTo: string): string;
+/**
+ * The inline-answer enhancement (portfolio arc §2): submits a reversible
+ * option's form as the urlencoded POST the forms-only gate expects, follows
+ * the redirect, and — because an answered decision leaves the open list —
+ * replaces ONLY that card with the answered receipt parsed from the
+ * decision page's own rendering, or removes the card. Anything unexpected
+ * (auth, a page that is not the decision's) navigates instead of inserting.
+ * Nothing else on the page is touched: typed input elsewhere survives.
+ */
+export declare function decisionAnswerScript(): string;
+/**
+ * Creating work is the product's first verb, so it gets a whole calm page:
+ * a title, the goal that becomes the scope draft, and the project it lands
+ * in — then straight to the approve card, which is the aha the flow serves.
+ */
+/** One queue card. Taken work renders pinned — visible, never draggable. */
+/**
+ * The request's own session facts, readable from anywhere below the
+ * dispatcher without threading them through forty call sites: the csrf
+ * token the chrome's switcher forms carry, and the path a switch returns
+ * to. AsyncLocalStorage follows the request's own async chain, so two
+ * interleaved requests never read each other's token.
+ */
+/** The person's pinned theme from their own cookie; null follows the device. */
+export declare function pinnedTheme(cookieHeader: string | undefined): "light" | "dark" | null;
+/** 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;
+/**
+ * A revision's lineage and ACTUAL terms, in the same words on the task
+ * page, the approval card, and chat (contract handoff task 2): which
+ * source and build it revises, the ancestry to its root, the terms the
+ * child really carries (read from its own scope — never restated from the
+ * brief), what is re-resolved for THIS approval, what never inherits, and
+ * — when the task continues a repair chain — the attempts used against
+ * the signed cap.
+ */
+export declare function revisionLineageWords(lineage: RevisionLineage): string[];
+/** Review priority: a deterministic, LABELED presentation aid over facts
+ * the done list already carries. Band 0 goes first; the words name why.
+ * It is never a verdict — the stored proof verdict stays the authority,
+ * and an operator's acceptance lowers a band without touching it. */
+export type ReviewPriority = {
+    band: 0 | 1 | 2;
+    label: "needs action" | "review" | "no flags";
+    reasons: string[];
+};
+export type ReviewQueueFacts = {
+    /** Only an exact current task/run match carries the assignment status. */
+    assignment?: AssignmentSnapshot | null;
+    proofReasons?: readonly string[];
+    runId: number | null;
+    outcome: string | null;
+    proofVerdict: ProofVerdict | null;
+    proofAccepted: boolean;
+    proofMatrix: readonly CriterionMatrixRow[];
+    ciFailing: boolean;
+    publicationState: string | null;
+};
+export declare function reviewPriorityOf(row: ReviewQueueFacts): ReviewPriority;
+/** Ranked, stable: band first, then newest completion, then task id — the
+ * same input always yields the same queue, whoever loads it. */
+export declare function rankReviewQueue<T extends ReviewQueueFacts & {
+    completedAt: string;
+    taskId: string;
+}>(rows: readonly T[]): (T & {
+    priority: ReviewPriority;
+})[];
+/** Whether a changed path sits inside the scope's signed "touches" — an
+ * exact file, a directory prefix (with or without its slash), or a plain
+ * `*` / `**` glob. Touches are advisory in the scope; here they only
+ * decide which files wear the "outside the signed touches" flag. */
+export declare function withinSignedTouches(path: string, touches: readonly string[]): boolean;
+/** A stable, attribute-safe anchor for one file of the sealed patch —
+ * derived from the path's bytes, never from the path's characters, so a
+ * hostile file name can neither break the id nor escape the attribute. */
+export declare function diffFileAnchor(path: string): string;
+export type ReviewFileRow = {
+    path: string;
+    additions: number | null;
+    deletions: number | null;
+    renamedFrom: string | null;
+    anchor: string | null;
+    outsideTouches: boolean;
+    cited: boolean;
+};
+/** The changed-file list's own review priority: outside the signed
+ * touches first, then files a machine cannot diff or a criterion never
+ * cited, then the rest by churn. Presentation only — the sealed patch
+ * keeps its own order beneath, byte for byte. */
+export declare function reviewFilePriority(file: ReviewFileRow, proofCitesPaths: boolean): ReviewPriority;
+export declare function orderChangedFiles(files: readonly ReviewFileRow[], proofCitesPaths: boolean): (ReviewFileRow & {
+    priority: ReviewPriority;
+})[];
+/** Older machine-checked results saved a mechanical sentence; say the same
+ * facts in plain words (the version id stays, shortened). */
+export declare function plainConclusionOf(conclusion: string): string;
+/** The facts region alone, for the open-run poll (A4). A finished run's
+ * fragment says so instead of quietly growing forms (finding 5), and a run
+ * that stopped being the task's live claim says so too — both carry the
+ * stop marker, so an open tab quits refetching a dead build (round-4
+ * finding 15). */
+export declare function runFactsFragment(run: Run, taskId: string, live: boolean, route?: RouteStamp | null): string;