toolroll 0.9.27 → 0.9.29

package/dist/telegram-flow.js

@@ -20,6 +20,7 @@
  * replies go. Both go through chooseFlowCard, for exactly that visit.
  */
 import { randomBytes } from "node:crypto";
+import { LIMITS } from "./decision.js";
 import { keptDraft } from "./flow-draft.js";
 import { decideFlowCard, draftFor, flowDefinitionOf } from "./flow-engine.js";
 import { chooseFlowCard, flowChoiceAt, flowSendPaths, readFlowSend } from "./flow-send.js";
@@ -148,7 +149,7 @@ export function applyFlowReply(store, binding, prompt, text, repos, now) {
         if (waiting.draft === null)
             return [{ kind: "say", text: "This decision has no draft to edit." }];
         if (said.length > DRAFT_LIMIT)
-            return [{ kind: "say", text: `Keep it under ${DRAFT_LIMIT} characters.` }];
+            return [{ kind: "say", text: `That's ${said.length.toLocaleString("en-US")} characters. Keep it to ${DRAFT_LIMIT.toLocaleString("en-US")}, or change it in Toolroll.` }];
         const kept = keptDraft(said);
         store.updateFlowCard(waiting.card.id, { outputs: { ...waiting.card.outputs, [waiting.draft.id]: kept } }, now);
         store.addFlowComment({ card: waiting.card.id, author: binding.approver, body: "Edited the draft in Telegram.", mentions: [] }, now);
@@ -158,9 +159,12 @@ export function applyFlowReply(store, binding, prompt, text, repos, now) {
         return [{ kind: "decide", keyboard: buttons.keyboard, tokens: buttons.tokens,
                 text: `${waiting.flow.name}: your version of the draft for “${waiting.card.title}”\n\n${kept}\n\nApprove to send it as written.` }];
     }
+    // A note over its limit is refused with the limit, never cut.
+    if (said.length > LIMITS.note)
+        return [{ kind: "say", text: `That's ${said.length.toLocaleString("en-US")} characters. Keep the note to ${LIMITS.note.toLocaleString("en-US")}, or send it back in Toolroll.` }];
     if (repos === null)
         return [{ kind: "say", text: "Couldn't check your projects just now. Reply again in a moment." }];
-    const decided = decideFlowCard(store, { card: waiting.card.id, decision: "send-back", note: said.slice(0, 2000), actor: binding.approver, repos, entry: prompt.entry }, now);
+    const decided = decideFlowCard(store, { card: waiting.card.id, decision: "send-back", note: said, actor: binding.approver, repos, entry: prompt.entry }, now);
     if (!decided.ok)
         return [{ kind: "say", text: decided.message }];
     store.retireTelegramFlowVisit(prompt.card, prompt.entry, now);

package/dist/test-temp.js

@@ -18,7 +18,7 @@ export const TEST_TEMP_PREFIXES = [
     "flow-goal-", "flow-scratch", "flows-chat-", "invoke-attest-", "knowledge-test-", "learning-", "peek-", "phone-origin-",
     "proposal-repo-", "race-", "refresh-migration-", "refresh-refusal-", "release-check-", "shared-chat-", "skills-test-",
     "task-status-surfaces-", "template-repo-", "template-test-", "v14-migrate-", "v17-migrate-", "watch-anchor-",
-    "needs-you-", "deps-lock-", "deps-state-", "upgrade-fresh-", "upgrade-path-", "deploy-restore-", "result-review-", "one-result-page-", "deploy-before-swap-", "one-vocabulary-", "accept-finishes-", "lead-promises-", "lead-people-",
+    "needs-you-", "deps-lock-", "deps-state-", "upgrade-fresh-", "upgrade-path-", "deploy-restore-", "result-review-", "one-result-page-", "deploy-before-swap-", "one-vocabulary-", "accept-finishes-", "lead-promises-", "lead-people-", "sizing-repo-",
     // Playwright's browser profiles and artifacts.
     "playwright_chromiumdev_profile-", "playwright_firefoxdev_profile-", "playwright-artifacts-",
 ];

package/dist/text-limits.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Text limits, in one place, and the one way a limit is met: a model is told the exact limit before it writes, an
+ * answer still over it is asked once to shorten (one repair turn), and an answer still over after that is kept whole
+ * in the record and linked, never chopped. Chat platforms' own message limits are met by splitting across messages.
+ *
+ * Limits apply when text is written. Reading never re-validates length, so a runtime with lower limits (0.9.23 to
+ * 0.9.26) still opens a store holding longer text (scripts/upgrade-path.mjs, the rollback leg).
+ */
+/** UTF-16 code units, the JavaScript and HTML maxlength measure, unless a name says bytes. */
+export declare const TEXT_LIMITS: {
+    /** A task's goal and its out-of-scope text. */
+    readonly goal: 8000;
+    readonly goalBytes: 32000;
+    /** Revise feedback, steering and decision notes. */
+    readonly note: 4000;
+    readonly noteBytes: 16000;
+    /** A flow work zone's instructions; nothing is held back for the card's details (they are attached when long). */
+    readonly flowInstructions: 8000;
+    /** A research report's summary, in UTF-8 bytes. */
+    readonly reportSummary: 2500;
+    /** What one flow step passes on to the steps after it. */
+    readonly stageOutput: 12000;
+};
+/** One chat message on each platform. Longer text is split across messages, never cut. Teams: the text one Adaptive Card
+ * holds, well inside its 28 KB message. */
+export declare const PLATFORM_LIMITS: {
+    readonly telegram: 4096;
+    readonly discord: 2000;
+    readonly slack: 4000;
+    readonly teams: 6000;
+};
+export type Platform = keyof typeof PLATFORM_LIMITS;
+/** The line a model reads before it writes a field with a limit. */
+export declare function limitRule(what: string, limit: number, unit?: "characters" | "bytes"): string;
+/** One field over its limit: what it is, its limit, and how long it came back. */
+export type Overrun = {
+    field: string;
+    limit: number;
+    length: number;
+    unit?: "characters" | "bytes";
+};
+/** How long a text is in a limit's unit. */
+export declare const lengthIn: (text: string, unit?: "characters" | "bytes") => number;
+/** The fields of `values` over their limits. */
+export declare function overruns(values: Record<string, string>, limits: Record<string, number>, unit?: "characters" | "bytes"): Overrun[];
+/** The repair turn's ask: each field over its limit, by how much, and the same answer again within it. */
+export declare function shortenAsk(over: readonly Overrun[]): string;
+/**
+ * Ask, check, and ask once more to shorten. `write` gets null the first time and the shorten ask the second.
+ * The second answer is returned whatever its length: the caller keeps it whole (and links it when it must).
+ */
+export declare function writeWithin<T>(write: (shorten: string | null) => Promise<T>, check: (answer: T) => Overrun[]): Promise<{
+    answer: T;
+    over: Overrun[];
+    repaired: boolean;
+}>;
+/**
+ * Text passed on under a limit: whole when it fits; otherwise kept whole in the record named by `where` and passed on
+ * as a pointer to it. Never a cut.
+ */
+export declare function passOn(text: string, limit: number, where: {
+    label: string;
+    href: string | null;
+}, holds?: string): {
+    text: string;
+    kept: boolean;
+};

package/dist/text-limits.js

@@ -0,0 +1,73 @@
+/**
+ * Text limits, in one place, and the one way a limit is met: a model is told the exact limit before it writes, an
+ * answer still over it is asked once to shorten (one repair turn), and an answer still over after that is kept whole
+ * in the record and linked, never chopped. Chat platforms' own message limits are met by splitting across messages.
+ *
+ * Limits apply when text is written. Reading never re-validates length, so a runtime with lower limits (0.9.23 to
+ * 0.9.26) still opens a store holding longer text (scripts/upgrade-path.mjs, the rollback leg).
+ */
+/** UTF-16 code units, the JavaScript and HTML maxlength measure, unless a name says bytes. */
+export const TEXT_LIMITS = {
+    /** A task's goal and its out-of-scope text. */
+    goal: 8_000,
+    goalBytes: 32_000,
+    /** Revise feedback, steering and decision notes. */
+    note: 4_000,
+    noteBytes: 16_000,
+    /** A flow work zone's instructions; nothing is held back for the card's details (they are attached when long). */
+    flowInstructions: 8_000,
+    /** A research report's summary, in UTF-8 bytes. */
+    reportSummary: 2_500,
+    /** What one flow step passes on to the steps after it. */
+    stageOutput: 12_000,
+};
+/** One chat message on each platform. Longer text is split across messages, never cut. Teams: the text one Adaptive Card
+ * holds, well inside its 28 KB message. */
+export const PLATFORM_LIMITS = { telegram: 4_096, discord: 2_000, slack: 4_000, teams: 6_000 };
+const count = (n) => n.toLocaleString("en-US");
+/** The line a model reads before it writes a field with a limit. */
+export function limitRule(what, limit, unit = "characters") {
+    return `${what}: at most ${count(limit)} ${unit}. Put the most important part first. Longer text is not cut: you will be asked to shorten it.`;
+}
+/** How long a text is in a limit's unit. */
+export const lengthIn = (text, unit = "characters") => unit === "bytes" ? Buffer.byteLength(text, "utf8") : text.length;
+/** The fields of `values` over their limits. */
+export function overruns(values, limits, unit = "characters") {
+    return Object.entries(limits).flatMap(([field, limit]) => {
+        const value = values[field];
+        if (value === undefined)
+            return [];
+        const length = lengthIn(value, unit);
+        return length > limit ? [{ field, limit, length, ...(unit === "bytes" ? { unit } : {}) }] : [];
+    });
+}
+/** The repair turn's ask: each field over its limit, by how much, and the same answer again within it. */
+export function shortenAsk(over) {
+    return [
+        "Your answer is over a limit:",
+        ...over.map(one => `- ${one.field} is ${count(one.length)} ${one.unit ?? "characters"}; the limit is ${count(one.limit)}.`),
+        "Answer again with the same decision and meaning, each field within its limit. Shorten by dropping repetition and detail, not facts that matter.",
+    ].join("\n");
+}
+/**
+ * Ask, check, and ask once more to shorten. `write` gets null the first time and the shorten ask the second.
+ * The second answer is returned whatever its length: the caller keeps it whole (and links it when it must).
+ */
+export async function writeWithin(write, check) {
+    const first = await write(null);
+    const over = check(first);
+    if (over.length === 0)
+        return { answer: first, over, repaired: false };
+    const second = await write(shortenAsk(over));
+    return { answer: second, over: check(second), repaired: true };
+}
+/**
+ * Text passed on under a limit: whole when it fits; otherwise kept whole in the record named by `where` and passed on
+ * as a pointer to it. Never a cut.
+ */
+export function passOn(text, limit, where, holds = "a step passes on") {
+    if (text.length <= limit)
+        return { text, kept: false };
+    const at = where.href === null ? where.label : `${where.label}: ${where.href}`;
+    return { text: `This is ${count(text.length)} characters, more than the ${count(limit)} ${holds}, so it is kept whole on ${at}.`, kept: true };
+}

package/dist/tier-report.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What sized routing saved (v2 routing), for `toolroll spend`: each task's
+ * tier (recorded on the task when its route is filed), how long it took
+ * from its first run to its first result, and whether it used a planner —
+ * grouped by tier, with what the light tier saved: the plans small changes
+ * skipped, results that came sooner, and spend below the everyday tier.
+ */
+import type { SpendItem } from "./spend.js";
+import type { Database } from "./store.js";
+export type TierTask = {
+    taskId: string;
+    tier: string;
+    size: string | null;
+    planRuns: number;
+    minutesToResult: number | null;
+    microusd: number;
+};
+export type TierRow = {
+    tier: string;
+    tasks: number;
+    results: number;
+    medianMinutesToResult: number | null;
+    planRuns: number;
+    microusd: number;
+};
+export type TierSaved = {
+    /** Small changes that built with no planner run. */
+    plansSkipped: number;
+    /** Those skipped plans at this month's median planner run, in minutes; null when no planner run was measured. */
+    planMinutesSaved: number | null;
+    /** How much sooner a light result came than an everyday one (medians), in minutes; null without both. */
+    minutesSoonerEach: number | null;
+    /** Light tasks' spend below the everyday tier's average task, in micro-USD; null when either is unpriced or $0. */
+    microusdSaved: number | null;
+};
+export type TierReport = {
+    tasks: TierTask[];
+    rows: TierRow[];
+    saved: TierSaved;
+};
+/** Every routed task with a run in [from, to), by tier, and what the light tier saved. `items` are the month's spend. */
+export declare function tierReport(db: Database, from: string, to: string, items: readonly SpendItem[]): TierReport;
+/** The spend report's lines: one per tier, then what the tiers saved. Empty when no routed task ran this month. */
+export declare function tierLines(report: TierReport, usd: (microusd: number) => string): string[];

package/dist/tier-report.js

@@ -0,0 +1,71 @@
+const TIER_ORDER = ["light", "routine", "strong", "override", "pinned"];
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+const minutesBetween = (from, to) => {
+    const ms = Date.parse(to) - Date.parse(from);
+    return Number.isFinite(ms) && ms >= 0 ? Math.round(ms / 6_000) / 10 : null;
+};
+/** Every routed task with a run in [from, to), by tier, and what the light tier saved. `items` are the month's spend. */
+export function tierReport(db, from, to, items) {
+    const spendOf = new Map();
+    for (const item of items)
+        if (item.taskId !== null)
+            spendOf.set(item.taskId, (spendOf.get(item.taskId) ?? 0) + (item.microusd ?? 0));
+    const rows = db.prepare(`SELECT r.external_id AS task, r.route_tier AS tier, r.size AS size,
+      (SELECT COUNT(*) FROM run p WHERE p.task_ref = r.id AND p.role = 'planner') AS plan_runs,
+      (SELECT MIN(f.started_at) FROM run f WHERE f.task_ref = r.id) AS first_started,
+      (SELECT MIN(b.finished_at) FROM run b WHERE b.task_ref = r.id AND b.role = 'builder' AND b.outcome IN ('built', 'no-change') AND b.finished_at IS NOT NULL) AS result_at
+    FROM task_ref r
+    WHERE r.route_tier IS NOT NULL AND EXISTS (SELECT 1 FROM run x WHERE x.task_ref = r.id AND x.started_at >= ? AND x.started_at < ?)
+    ORDER BY r.id`).all(from, to);
+    const tasks = rows.map(row => ({
+        taskId: String(row["task"]),
+        tier: String(row["tier"]),
+        size: row["size"] == null ? null : String(row["size"]),
+        planRuns: Number(row["plan_runs"] ?? 0),
+        minutesToResult: row["first_started"] == null || row["result_at"] == null ? null : minutesBetween(String(row["first_started"]), String(row["result_at"])),
+        microusd: spendOf.get(String(row["task"])) ?? 0,
+    }));
+    const tiers = [...new Set(tasks.map(one => one.tier))].sort((a, b) => (TIER_ORDER.indexOf(a) + 1 || 99) - (TIER_ORDER.indexOf(b) + 1 || 99));
+    const byTier = tiers.map(tier => {
+        const mine = tasks.filter(one => one.tier === tier);
+        const done = mine.flatMap(one => (one.minutesToResult === null ? [] : [one.minutesToResult]));
+        return { tier, tasks: mine.length, results: done.length, medianMinutesToResult: median(done), planRuns: mine.reduce((sum, one) => sum + one.planRuns, 0), microusd: mine.reduce((sum, one) => sum + one.microusd, 0) };
+    });
+    const plansSkipped = tasks.filter(one => one.size === "small" && one.planRuns === 0).length;
+    const plannerMinutes = db.prepare("SELECT started_at, finished_at FROM run WHERE role = 'planner' AND finished_at IS NOT NULL AND started_at >= ? AND started_at < ?").all(from, to)
+        .flatMap(row => { const m = minutesBetween(String(row["started_at"]), String(row["finished_at"])); return m === null ? [] : [m]; });
+    const perPlan = median(plannerMinutes);
+    const light = byTier.find(one => one.tier === "light") ?? null;
+    const routine = byTier.find(one => one.tier === "routine") ?? null;
+    const sooner = light?.medianMinutesToResult != null && routine?.medianMinutesToResult != null && routine.medianMinutesToResult > light.medianMinutesToResult
+        ? Math.round((routine.medianMinutesToResult - light.medianMinutesToResult) * 10) / 10 : null;
+    const perTask = (row) => (row === null || row.tasks === 0 || row.microusd <= 0 ? null : row.microusd / row.tasks);
+    const lightEach = light === null || light.tasks === 0 ? null : light.microusd / light.tasks;
+    const routineEach = perTask(routine);
+    const microusdSaved = light !== null && lightEach !== null && routineEach !== null && routineEach > lightEach ? Math.round((routineEach - lightEach) * light.tasks) : null;
+    return {
+        tasks,
+        rows: byTier,
+        saved: { plansSkipped, planMinutesSaved: perPlan === null || plansSkipped === 0 ? null : Math.round(perPlan * plansSkipped), minutesSoonerEach: sooner, microusdSaved },
+    };
+}
+const minutesWords = (minutes) => (minutes >= 90 ? `${Math.round(minutes / 6) / 10}h` : `${Math.round(minutes)}m`);
+/** The spend report's lines: one per tier, then what the tiers saved. Empty when no routed task ran this month. */
+export function tierLines(report, usd) {
+    if (report.rows.length === 0)
+        return [];
+    const lines = report.rows.map(row => `  ${`${row.tier} tier`.padEnd(24)} ${row.tasks} ${row.tasks === 1 ? "task" : "tasks"} · ${row.medianMinutesToResult === null ? "no result yet" : `${minutesWords(row.medianMinutesToResult)} to a result`} · ${row.planRuns} ${row.planRuns === 1 ? "plan" : "plans"} · ${usd(row.microusd)}`);
+    const saved = report.saved;
+    const parts = [
+        ...(saved.plansSkipped === 0 ? [] : [`${saved.plansSkipped} ${saved.plansSkipped === 1 ? "plan" : "plans"} skipped${saved.planMinutesSaved === null ? "" : ` (~${minutesWords(saved.planMinutesSaved)} of planning)`}`]),
+        ...(saved.minutesSoonerEach === null ? [] : [`light results ~${minutesWords(saved.minutesSoonerEach)} sooner each`]),
+        ...(saved.microusdSaved === null ? [] : [`~${usd(saved.microusdSaved)} below the everyday tier`]),
+    ];
+    return [...lines, `  ${"tiers saved".padEnd(24)} ${parts.length === 0 ? "nothing yet — no small change has run on the light tier" : parts.join(", ")}`];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.27",
+  "version": "0.9.29",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"