toolroll 0.5.0

package/dist/limits-ui.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Limits on the Tasks page (v105): each subscription's usage windows, as the
+ * provider last said, and each monthly budget, one tile each. A subscription
+ * costs nothing per run, so its windows are what bind it; budgets bind work
+ * billed to an API key. An instance operator's view.
+ */
+import type { BrowserLimits } from "./browser-workspace.js";
+import { type BudgetState } from "./spend.js";
+/** "in 25 min", "in 2 h 10 min", or a day and hour ("Fri 11 PM") beyond a day. */
+export declare function resetWords(resetsAt: string, now: Date): string;
+export declare function limitsView(windows: readonly {
+    provider: string;
+    window: string;
+    usedPercent: number;
+    windowMinutes: number | null;
+    resetsAt: string | null;
+    reached: boolean;
+    plan: string | null;
+    observedAt: string;
+}[], budgets: readonly BudgetState[], names: {
+    project: (repo: string) => string;
+    teammate: (id: number) => string;
+}, now: Date): BrowserLimits | null;
+/** The same tiles for the page without scripts. */
+export declare function limitsHtml(limits: BrowserLimits | null): string;
+export declare const LIMITS_CSS: string;

package/dist/limits-ui.js

@@ -0,0 +1,67 @@
+import { windowLabel } from "./provider-limits.js";
+import { usd } from "./spend.js";
+const PROVIDER_NAMES = { claude: "Claude", codex: "Codex", gemini: "Gemini" };
+/** Plan names worth showing; anything else (an internal billing name) is left off. */
+const PLAN_NAMES = { free: "Free", plus: "Plus", pro: "Pro", max: "Max", team: "Team", business: "Business", enterprise: "Enterprise", edu: "Edu" };
+/** "in 25 min", "in 2 h 10 min", or a day and hour ("Fri 11 PM") beyond a day. */
+export function resetWords(resetsAt, now) {
+    const minutes = Math.max(1, Math.round((Date.parse(resetsAt) - now.getTime()) / 60_000));
+    if (minutes < 60)
+        return `in ${minutes} min`;
+    if (minutes < 24 * 60)
+        return `in ${Math.floor(minutes / 60)} h${minutes % 60 === 0 ? "" : ` ${minutes % 60} min`}`;
+    return new Intl.DateTimeFormat("en-US", { weekday: "short", hour: "numeric" }).format(new Date(resetsAt)).replace(",", "");
+}
+const ago = (iso, now) => {
+    const minutes = Math.max(0, Math.round((now.getTime() - Date.parse(iso)) / 60_000));
+    return minutes < 60 ? `${minutes}m ago` : minutes < 48 * 60 ? `${Math.round(minutes / 60)}h ago` : `${Math.round(minutes / 1440)}d ago`;
+};
+const toneOf = (percent, reached) => reached || percent >= 100 ? "danger" : percent >= 80 ? "warning" : "neutral";
+export function limitsView(windows, budgets, names, now) {
+    const tiles = [];
+    for (const one of windows) {
+        // A window that has turned over since the reading starts again from nothing.
+        const turned = one.resetsAt !== null && Date.parse(one.resetsAt) <= now.getTime();
+        const percent = turned ? 0 : one.usedPercent;
+        const reached = !turned && one.reached;
+        const stale = now.getTime() - Date.parse(one.observedAt) > 30 * 60_000;
+        const provider = PROVIDER_NAMES[one.provider] ?? one.provider;
+        const plan = one.plan === null ? "" : Object.hasOwn(PLAN_NAMES, one.plan.toLowerCase()) ? ` ${PLAN_NAMES[one.plan.toLowerCase()]}` : "";
+        tiles.push({
+            key: `${one.provider}:${one.window}`, name: `${provider}${plan}`, window: windowLabel(one.window, one.windowMinutes),
+            value: String(Math.round(percent)), unit: "%", percent, tone: toneOf(percent, reached), marks: [], href: null,
+            detail: turned ? "New window" : `${reached ? "Used up · resets" : "Resets"} ${one.resetsAt === null ? "later" : resetWords(one.resetsAt, now)}${stale ? ` · read ${ago(one.observedAt, now)}` : ""}`,
+            title: `${provider} said this ${ago(one.observedAt, now)}`,
+        });
+    }
+    for (const budget of budgets) {
+        const over = budget.spentMicrousd >= budget.limitMicrousd;
+        const name = budget.scope === "installation" ? "Everything" : budget.scope === "project" ? names.project(budget.key)
+            : budget.scope === "teammate" ? names.teammate(Number(budget.key)) : budget.key;
+        tiles.push({
+            key: `budget:${budget.id}`, name, window: "Budget", value: usd(budget.spentMicrousd), unit: `of ${usd(budget.limitMicrousd)}`,
+            percent: budget.percent, tone: over ? (budget.hardStop ? "danger" : "warning") : budget.percent >= 80 ? "warning" : "neutral", marks: [50, 80], href: "/spend",
+            detail: over && budget.hardStop ? "Used up · API work waits" : budget.hardStop ? "Stops API work at 100%" : "Alerts only",
+            title: `This month's spend billed to API keys${budget.unpriced > 0 ? `; ${budget.unpriced} without a price` : ""}`,
+        });
+    }
+    return tiles.length === 0 ? null : { tiles };
+}
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+/** The same tiles for the page without scripts. */
+export function limitsHtml(limits) {
+    if (limits === null)
+        return "";
+    return `<section class="limits" aria-label="Limits"><ul>${limits.tiles.map(tile => {
+        const body = `<p class="limit-name"><strong>${e(tile.name)}</strong> ${e(tile.window)}</p><p class="limit-value"><strong>${e(tile.value)}</strong> ${e(tile.unit)}</p>` +
+            `<span class="limit-bar" aria-hidden="true"><span style="width:${Math.min(100, Math.max(0, tile.percent))}%"></span></span><p class="limit-detail">${e(tile.detail)}</p>`;
+        return `<li class="limit limit-${tile.tone}" data-limit="${e(tile.key)}"${tile.title === null ? "" : ` title="${e(tile.title)}"`}>${tile.href === null ? body : `<a href="${e(tile.href)}">${body}</a>`}</li>`;
+    }).join("")}</ul></section>`;
+}
+export const LIMITS_CSS = `.limits ul{list-style:none;margin:0 0 16px;padding:0;display:grid;grid-template-columns:repeat(auto-fill,minmax(176px,1fr));gap:8px}` +
+    `.limit{border:1px solid var(--border);border-radius:10px;background:var(--card);padding:12px 14px;min-width:0}.limit a{color:inherit;text-decoration:none;display:block}` +
+    `.limit p{margin:0}.limit-name{font-size:12px;color:var(--muted-foreground);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.limit-name strong{color:var(--foreground);font-weight:500}` +
+    `.limit-value{margin-top:8px!important;font-size:12px;color:var(--muted-foreground);font-variant-numeric:tabular-nums}.limit-value strong{font-size:22px;font-weight:600;color:var(--foreground);letter-spacing:-.02em}` +
+    `.limit-bar{display:block;height:6px;border-radius:3px;background:var(--muted);overflow:hidden;margin-top:10px}.limit-bar span{display:block;height:100%;border-radius:3px;background:var(--foreground)}` +
+    `.limit-warning .limit-bar span{background:var(--warning)}.limit-danger .limit-bar span{background:var(--danger)}.limit-danger .limit-value strong{color:var(--danger)}` +
+    `.limit-detail{margin-top:8px!important;font-size:11.5px;color:var(--muted-foreground);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}`;

package/dist/link.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Putting the command on PATH, as an explicit act.
+ *
+ * Toolroll refuses to install things on an operator's behalf — it prints
+ * the command and its side effects and lets them run it. A tool that applied
+ * that rule to `bd init` and then quietly edited PATH during its own install
+ * would not deserve to be believed, so this is a command you run, it shows
+ * you what it will do before it does it, and `unlink` undoes it exactly.
+ *
+ * Three rules hold throughout: never sudo, never a directory outside the home
+ * directory unless explicitly named, and never delete anything that is not
+ * something we put there.
+ *
+ * Two mechanisms, because "a command on PATH" means different things. On POSIX
+ * it is a symlink with the execute bit set. On Windows the shell resolves
+ * commands through PATHEXT, so an extensionless symlink is invisible no matter
+ * which directory it sits in — there it is a `.cmd` shim, which is also what
+ * npm writes, and which needs no Developer Mode to create.
+ */
+/** What you type. */
+export declare const BIN_NAME = "toolroll";
+/** What lands on disk. Windows needs the extension to resolve it through PATHEXT. */
+export declare const LINK_FILE: string;
+export type TargetChoice = {
+    dir: string;
+    onPath: boolean;
+};
+export type LinkPlan = {
+    action: "create";
+    source: string;
+    target: string;
+} | {
+    action: "already";
+    source: string;
+    target: string;
+} | {
+    action: "replace";
+    source: string;
+    target: string;
+    current: string;
+} | {
+    action: "conflict";
+    source: string;
+    target: string;
+    reason: string;
+};
+export type UnlinkPlan = {
+    action: "remove";
+    target: string;
+    current: string;
+} | {
+    action: "absent";
+    target: string;
+} | {
+    action: "foreign";
+    target: string;
+    reason: string;
+};
+/**
+ * Where the link should go. Only directories inside the home directory are
+ * ever proposed: everything else needs sudo, and needing sudo to read your own
+ * git repositories would be absurd.
+ */
+export declare function chooseTarget(options: {
+    pathEntries: readonly string[];
+    home: string;
+    override?: string;
+}): TargetChoice;
+export declare function planLink(source: string, dir: string): Promise<LinkPlan>;
+export declare function applyLink(plan: LinkPlan): Promise<void>;
+export declare function planUnlink(dir: string): Promise<UnlinkPlan>;
+export declare function applyUnlink(plan: UnlinkPlan): Promise<void>;

package/dist/link.js

@@ -0,0 +1,217 @@
+/**
+ * Putting the command on PATH, as an explicit act.
+ *
+ * Toolroll refuses to install things on an operator's behalf — it prints
+ * the command and its side effects and lets them run it. A tool that applied
+ * that rule to `bd init` and then quietly edited PATH during its own install
+ * would not deserve to be believed, so this is a command you run, it shows
+ * you what it will do before it does it, and `unlink` undoes it exactly.
+ *
+ * Three rules hold throughout: never sudo, never a directory outside the home
+ * directory unless explicitly named, and never delete anything that is not
+ * something we put there.
+ *
+ * Two mechanisms, because "a command on PATH" means different things. On POSIX
+ * it is a symlink with the execute bit set. On Windows the shell resolves
+ * commands through PATHEXT, so an extensionless symlink is invisible no matter
+ * which directory it sits in — there it is a `.cmd` shim, which is also what
+ * npm writes, and which needs no Developer Mode to create.
+ */
+import { chmod, mkdir, lstat, readFile, readlink, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+const isWindows = process.platform === "win32";
+/** What you type. */
+export const BIN_NAME = "toolroll";
+/** What lands on disk. Windows needs the extension to resolve it through PATHEXT. */
+export const LINK_FILE = isWindows ? `${BIN_NAME}.cmd` : BIN_NAME;
+/** Owner, group, and other execute — the same bits npm sets on a package bin. */
+const EXECUTABLE_BITS = 0o111;
+/**
+ * How a shim is known to be ours. The symlink case can ask the filesystem what
+ * it is; a `.cmd` is an ordinary file, so it has to say so in its own text or
+ * `unlink` could not tell it from someone else's program of the same name.
+ */
+const SHIM_MARKER = "toolroll-link: generated by `toolroll link`";
+/** Shims written before the rename to Toolroll stay ours. */
+const LEGACY_SHIM_MARKER = "standing-orders-link: generated by `standing-orders link`";
+/**
+ * Windows path comparison is case-insensitive, and a PATH entry may or may not
+ * carry a trailing separator. Comparing the raw strings means a directory that
+ * is on PATH gets reported as missing from it.
+ */
+function comparablePath(path) {
+    const trimmed = path.length > 1 && path.endsWith(sep) ? path.slice(0, -1) : path;
+    return isWindows ? trimmed.toLowerCase() : trimmed;
+}
+function samePath(left, right) {
+    return comparablePath(left) === comparablePath(right);
+}
+/** Whether `path` is the home directory or sits beneath it. */
+function isInside(path, home) {
+    const inner = comparablePath(path);
+    const outer = comparablePath(home);
+    return inner === outer || inner.startsWith(outer + sep);
+}
+/**
+ * Where the link should go. Only directories inside the home directory are
+ * ever proposed: everything else needs sudo, and needing sudo to read your own
+ * git repositories would be absurd.
+ */
+export function chooseTarget(options) {
+    const { pathEntries, home, override } = options;
+    const isOnPath = (dir) => pathEntries.some(entry => samePath(entry, dir));
+    if (override !== undefined) {
+        const dir = resolve(override);
+        return { dir, onPath: isOnPath(dir) };
+    }
+    const conventional = [join(home, ".local", "bin"), join(home, "bin")];
+    const preferred = conventional.find(isOnPath);
+    if (preferred !== undefined)
+        return { dir: preferred, onPath: true };
+    const homeOwned = pathEntries.find(entry => isInside(entry, home));
+    if (homeOwned !== undefined)
+        return { dir: homeOwned, onPath: true };
+    // Nothing usable on PATH. Propose the conventional location and say so.
+    return { dir: conventional[0], onPath: false };
+}
+export async function planLink(source, dir) {
+    const target = join(dir, LINK_FILE);
+    const existing = await describeExisting(target);
+    if (existing === null)
+        return { action: "create", source, target };
+    if (existing.kind === "foreign") {
+        return { action: "conflict", source, target, reason: existing.reason };
+    }
+    if (samePath(existing.pointsTo, source))
+        return { action: "already", source, target };
+    return { action: "replace", source, target, current: existing.pointsTo };
+}
+export async function applyLink(plan) {
+    if (plan.action === "conflict") {
+        throw new Error(`${plan.target}: ${plan.reason} — remove it yourself if you want it gone`);
+    }
+    if (plan.action === "already")
+        return;
+    await mkdir(dirname(plan.target), { recursive: true });
+    // Only ever removing a shim we recognise, never someone else's file.
+    if (plan.action === "replace")
+        await unlink(plan.target);
+    if (isWindows) {
+        await writeFile(plan.target, shimText(plan.source));
+        return;
+    }
+    await symlink(plan.source, plan.target);
+    await ensureExecutable(plan.source);
+}
+/**
+ * `%*` forwards arguments with their quoting intact — the same mechanism npm's
+ * own generated shims use — and `EXIT /B` hands the command's exit code back to
+ * the shell, without which a failing scan would look like a success to anything
+ * that checked.
+ *
+ * The path is written with `%` doubled, because a percent sign is legal in a
+ * Windows path and cmd would otherwise read `%Foo%` in it as a variable and
+ * substitute it away. The `REM source:` line keeps the path verbatim: it is
+ * read back by this program, not by cmd.
+ *
+ * `SETLOCAL DisableDelayedExpansion` is not ceremony. Delayed expansion is
+ * inherited — a shim invoked under `cmd /v:on`, or from a batch file that
+ * enabled it, would have every `!` in the path *and in the arguments* eaten
+ * before node saw them, turning `a!name!b` into `ab` silently. Disabling it for
+ * our own scope is the only way to be sure. `ENDLOCAL &` shares a line with the
+ * exit so that `%ERRORLEVEL%` is read inside the scope, before it is torn down.
+ *
+ * One inherited quirk remains, worth knowing before someone reports it as a
+ * bug: a batch file reaching this through CALL has its arguments parsed a
+ * second time by cmd, which doubles any caret in them. That happens to
+ * `CALL node ...` just the same, with no shim involved, and no batch file can
+ * avoid it — only a compiled launcher could. The tests pin the shim to being
+ * transparent rather than to being immune.
+ */
+function shimText(source) {
+    return [
+        "@ECHO off",
+        `REM ${SHIM_MARKER}; safe to delete`,
+        `REM source: ${source}`,
+        "SETLOCAL DisableDelayedExpansion",
+        `node "${source.replaceAll("%", "%%")}" %*`,
+        "ENDLOCAL & EXIT /B %ERRORLEVEL%",
+        "",
+    ].join("\r\n");
+}
+/** The source a shim points at, or null when the text is not one of ours. */
+function readShimSource(text) {
+    if (!text.includes(SHIM_MARKER) && !text.includes(LEGACY_SHIM_MARKER))
+        return null;
+    const declared = /^REM source: (.+)$/m.exec(text);
+    return declared?.[1]?.trim() ?? null;
+}
+/**
+ * tsc emits a file with the shebang intact but without the execute bit, so a
+ * symlink to it fails with "permission denied" the first time it is typed.
+ * Windows has no such bit, and chmod there is a no-op at best.
+ */
+async function ensureExecutable(source) {
+    if (isWindows)
+        return;
+    const stats = await stat(source);
+    const wanted = stats.mode | EXECUTABLE_BITS;
+    if (wanted !== stats.mode)
+        await chmod(source, wanted);
+}
+export async function planUnlink(dir) {
+    const target = join(dir, LINK_FILE);
+    const existing = await describeExisting(target);
+    if (existing === null)
+        return { action: "absent", target };
+    if (existing.kind === "foreign") {
+        return { action: "foreign", target, reason: existing.reason };
+    }
+    return { action: "remove", target, current: existing.pointsTo };
+}
+export async function applyUnlink(plan) {
+    if (plan.action === "foreign") {
+        throw new Error(`${plan.target}: ${plan.reason} — leaving it alone`);
+    }
+    if (plan.action === "absent")
+        return;
+    await unlink(plan.target);
+}
+/**
+ * null when nothing is there. Otherwise: ours, and what it points at, or
+ * foreign, and why we will not touch it.
+ */
+async function describeExisting(target) {
+    let stats;
+    try {
+        stats = await lstat(target);
+    }
+    catch {
+        return null;
+    }
+    if (isWindows) {
+        if (!stats.isFile()) {
+            return { kind: "foreign", reason: "something that is not a file is already there" };
+        }
+        let text;
+        try {
+            text = await readFile(target, "utf8");
+        }
+        catch {
+            return { kind: "foreign", reason: "something unreadable is already there" };
+        }
+        const pointsTo = readShimSource(text);
+        if (pointsTo === null) {
+            return { kind: "foreign", reason: "a program we did not write is already there" };
+        }
+        return { kind: "ours", pointsTo };
+    }
+    if (!stats.isSymbolicLink()) {
+        return { kind: "foreign", reason: "something that is not a link is already there" };
+    }
+    // readlink returns the link's raw text, which may be relative. Comparing that
+    // against an absolute source would call a perfectly good link stale and
+    // replace it on every run.
+    const raw = await readlink(target);
+    return { kind: "ours", pointsTo: resolve(dirname(target), raw) };
+}

package/dist/live.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The live window (arc 1): what the running agent is saying, on disk, for
+ * the run page to poll — and NOTHING else.
+ *
+ * This file is display state, not evidence. No artifact row points at it,
+ * no digest binds it, and the page that renders it says so: the machine
+ * running the agent could alter it. It exists so a person can watch work
+ * happen without a terminal, and every byte in it went through the same
+ * sanitize discipline as the peek: controls stripped, credential-shaped
+ * lines replaced whole, tool activity described in OUR fixed vocabulary —
+ * event metadata is never echoed.
+ *
+ * Fail-soft everywhere: a live view that cannot be written must never
+ * break, slow, or reclassify a build.
+ */
+export declare const LIVE_LINE_CAP: number;
+export declare const LIVE_FILE_CAP: number;
+export declare const LIVE_CAP_MARKER = "[the live view stopped at its size cap \u2014 the run record continues]";
+export declare const LIVE_REDACTED_LINE = "[a credential-shaped line was redacted]";
+/** Finalized runs keep their live file this long for the final drain. */
+export declare const LIVE_RETAIN_MS: number;
+/** The bounded sweep: at most this many FINALIZED files survive a pass. */
+export declare const LIVE_FILE_BOUND = 500;
+export declare function liveDir(root: string): string;
+/** The exact filename, from the numeric id and nothing else — no user
+ * input is ever parsed into this path. */
+export declare function liveLogPath(root: string, runId: number): string;
+/**
+ * One stream event → zero or more display lines, in the fixed vocabulary.
+ * Assistant TEXT is the agent's own words (sanitized below); tool use is a
+ * headline; everything else — tool results, deltas, results, subagent
+ * chatter — renders nothing in v1.
+ */
+export declare function renderTranscriptLines(event: Record<string, unknown>): string[];
+/** Sanitize one display line: strip, redact whole on any secret hit, cap. */
+export declare function sanitizeTranscriptLine(line: string): string;
+export type LiveLog = {
+    observe(event: Record<string, unknown>): void;
+    close(): void;
+};
+/**
+ * Open the run's live file for appending. The directory is 0700, the file
+ * 0600 and CREATED HERE (O_EXCL: a name that already exists — whatever put
+ * it there — is refused, not appended to), opened O_NOFOLLOW with the
+ * descriptor retained for the run's whole duration. Returns null on any
+ * failure: no live view is ever worth a build.
+ */
+export declare function openLiveLog(root: string, runId: number): LiveLog | null;
+export type LiveWindowRead = {
+    ok: true;
+    text: string;
+    nextOffset: number;
+    eof: boolean;
+} | {
+    ok: false;
+    reason: "missing" | "replaced" | "unreadable";
+};
+/**
+ * Read the live file from a byte offset, returning only COMPLETE lines
+ * (through the last LF in the window). The descriptor is the authority:
+ * opened O_NOFOLLOW, proved a regular file, measured and read through
+ * itself. A file smaller than the offset was replaced — the caller resets,
+ * visibly, never silently duplicating (arc 1 §4). `allowTail` (the final
+ * drain) returns the unterminated tail after finalization.
+ */
+export declare function readLiveWindow(root: string, runId: number, from: number, allowTail?: boolean): LiveWindowRead;
+export type LiveSweepVerdict = {
+    /** run id, or null when the name is not a run's file. */
+    runId: number | null;
+    fileName: string;
+    mtimeMs: number;
+};
+/**
+ * Enumerate the live directory for the reconcile sweep. Pure listing — the
+ * CALLER decides which runs are finalized and when; this module only
+ * refuses to guess. Non-run names are reported with runId null (orphans
+ * from nothing this plane wrote; aged on mtime like everything else).
+ */
+export declare function listLiveFiles(root: string): LiveSweepVerdict[];
+/** Remove one live file, silently: a sweep never throws over display state. */
+export declare function removeLiveFile(root: string, fileName: string): void;
+/**
+ * The reconcile sweep (arc 1 §2): ACTIVE runs are exempt ABSOLUTELY — the
+ * transport's no-truncation assumption depends on it. Finalized runs age
+ * from finished_at; orphans (no run row, or a name this plane never
+ * writes) age from mtime; and the 500-file bound applies only WITHIN the
+ * finalized-or-orphan set, oldest first.
+ */
+export declare function sweepLiveLogs(store: {
+    getRun(id: number): {
+        outcome: string | null;
+        finishedAt: string | null;
+    } | null;
+}, root: string, now: Date): {
+    removed: string[];
+};