toolroll 0.5.0

package/dist/flow-scripts.js

@@ -0,0 +1,73 @@
+/**
+ * Project scripts (v84): a library of reusable steps that run with no AI.
+ * A script is named — "run-tests", "enrich-lead", "export-orders" — and
+ * made on a flow's Scripts panel or drafted by the lead in chat. v90: it is
+ * written in shell, Python or Node, or runs a file already in the project.
+ * Any flow in the project uses it by name from a "Run a script" zone (and a
+ * schedule can run one to make cards), so one script can be improved once
+ * for every flow, and the insights show how each script does across them.
+ * Each save is a new version; runs record which ran.
+ */
+import { createHash } from "node:crypto";
+import { scanForSecrets } from "./evidence.js";
+import { flowDefinitionOf } from "./flow-engine.js";
+import { SCRIPT_LANGUAGES, SCRIPT_NAME } from "./flows.js";
+/** A script as it would be saved, checked in plain words. Throws. */
+export function validateScript(input) {
+    const name = typeof input.name === "string" ? input.name.trim().toLowerCase() : "";
+    if (!SCRIPT_NAME.test(name))
+        throw new Error("Name the script in lowercase letters, numbers and dashes, like run-tests.");
+    const about = typeof input.about === "string" ? input.about.replace(/\s+/g, " ").trim() : "";
+    if (about === "" || about.length > 160)
+        throw new Error("Say in one line what the script checks or does.");
+    const language = input.language === undefined || input.language === null || input.language === "" ? "shell" : input.language;
+    if (!SCRIPT_LANGUAGES.includes(language))
+        throw new Error("Choose the script's language: shell, Python or Node.");
+    const file = typeof input.file === "string" && input.file.trim() !== "" ? input.file.trim().replace(/^\.\//, "") : null;
+    if (file !== null && (file.length > 200 || file.startsWith("/") || file.split(/[\\/]/).includes("..") || !/^[A-Za-z0-9._/@+-]+$/.test(file)))
+        throw new Error("Give the file as a path inside the project, like scripts/enrich.py.");
+    const body = typeof input.body === "string" ? input.body.replace(/\r\n/g, "\n").trim() : "";
+    if (body === "" && file === null)
+        throw new Error("Write the script, or name a file in the project for it to run.");
+    if (body !== "" && file !== null)
+        throw new Error("A script either is written here or runs a file in the project, not both.");
+    if (body.length > 20_000)
+        throw new Error("Keep a script under 20,000 characters.");
+    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(body))
+        throw new Error("The script has hidden characters in it.");
+    if (scanForSecrets(`${about}\n${body}`).length > 0)
+        throw new Error("That looks like a key or password. Keep secrets out of scripts; read them from the environment on this computer.");
+    const minutes = typeof input.timeoutMinutes === "number" && Number.isFinite(input.timeoutMinutes) ? Math.round(input.timeoutMinutes) : typeof input.timeoutMinutes === "string" && input.timeoutMinutes.trim() !== "" ? Number(input.timeoutMinutes) : 15;
+    if (!Number.isInteger(minutes) || minutes < 1 || minutes > 60)
+        throw new Error("A script may run for 1 to 60 minutes.");
+    return { name, about, body, timeoutMinutes: minutes, language: language, file };
+}
+/** What a run is held to. A shell script written here keeps its v84 digest. */
+export const scriptDigest = (draft) => createHash("sha256").update((draft.language ?? "shell") === "shell" && (draft.file ?? null) === null ? `${draft.body}\0${draft.timeoutMinutes}` : `${draft.body}\0${draft.timeoutMinutes}\0${draft.language}\0${draft.file ?? ""}`).digest("hex").slice(0, 32);
+/** Save a script (a new version when it exists). */
+export function saveScript(store, repo, input, actor, now) {
+    let draft;
+    try {
+        draft = validateScript(input);
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : "That script isn't valid." };
+    }
+    const current = store.flowScript(repo, draft.name);
+    if (current !== null && current.digest === scriptDigest(draft) && current.about === draft.about)
+        return { ok: true, said: "No changes to save.", version: current.version };
+    const version = store.saveFlowScript({ repo, ...draft, digest: scriptDigest(draft), by: actor }, now);
+    return { ok: true, said: current === null ? `Saved the ${draft.name} script. Any flow in this project can run it.` : `Saved version ${version} of ${draft.name}. Every flow that runs it uses this version from now on.`, version };
+}
+/** The flows and zones in a project that run each script. */
+export function scriptUses(store, repo) {
+    const uses = new Map();
+    for (const flow of store.listFlows([repo]))
+        for (const stage of flowDefinitionOf(flow)?.stages ?? [])
+            if (stage.kind === "check" && stage.script !== null)
+                uses.set(stage.script, [...uses.get(stage.script) ?? [], { flow: flow.id, flowName: flow.name, zone: stage.title }]);
+    return uses;
+}
+export function scriptWords(script) {
+    return `${script.name} (version ${script.version}, up to ${script.timeoutMinutes} min): ${script.about}`;
+}

package/dist/flow-secrets.d.ts

@@ -0,0 +1,13 @@
+export declare const SECRET_NAME: RegExp;
+/** Any saved secret's value that shows up in output, replaced (a web response, a tool's answer, a script's output). */
+export declare const scrubSecrets: (text: string, secrets: Record<string, string>) => string;
+export declare function readFlowSecrets(dir: string | null, repo: string): Record<string, string>;
+export declare function flowSecretNames(dir: string | null, repo: string): string[];
+/** Set (or, with an empty value, remove) one of a project's secrets. Names are CAPITALS_AND_UNDERSCORES. */
+export declare function setFlowSecret(dir: string, repo: string, name: string, value: string): {
+    ok: true;
+    said: string;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/flow-secrets.js

@@ -0,0 +1,45 @@
+/**
+ * A project's flow secrets (v87; v90 for scripts too): named values kept in
+ * a 0600 file beside the database, one file per project. Web requests use
+ * them in headers ({{secret.NAME}}), and code steps get the ones they name as
+ * environment variables. Their values never reach a card, a log or a page.
+ * Its own module, with nothing but the file system, so triggers and the step
+ * runners can read it without an import cycle.
+ */
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,39}$/;
+const secretsFile = (dir, repo) => join(dir, "flow-secrets", `${createHash("sha256").update(repo).digest("hex").slice(0, 24)}.json`);
+/** Any saved secret's value that shows up in output, replaced (a web response, a tool's answer, a script's output). */
+export const scrubSecrets = (text, secrets) => Object.values(secrets).filter(value => value.length >= 6).reduce((out, value) => out.split(value).join("[secret]"), text);
+export function readFlowSecrets(dir, repo) {
+    if (dir === null)
+        return {};
+    try {
+        return JSON.parse(readFileSync(secretsFile(dir, repo), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function flowSecretNames(dir, repo) {
+    return Object.keys(readFlowSecrets(dir, repo)).sort();
+}
+/** Set (or, with an empty value, remove) one of a project's secrets. Names are CAPITALS_AND_UNDERSCORES. */
+export function setFlowSecret(dir, repo, name, value) {
+    if (!SECRET_NAME.test(name))
+        return { ok: false, message: "Name the secret in capitals, like API_TOKEN." };
+    const secrets = readFlowSecrets(dir, repo);
+    const trimmed = value.trim();
+    if (trimmed === "")
+        delete secrets[name];
+    else if (trimmed.length > 4000 || /[\r\n]/.test(trimmed))
+        return { ok: false, message: "That doesn't look like a secret: keep it to one line." };
+    else
+        secrets[name] = trimmed;
+    mkdirSync(join(dir, "flow-secrets"), { recursive: true, mode: 0o700 });
+    writeFileSync(secretsFile(dir, repo), JSON.stringify(secrets), { mode: 0o600 });
+    chmodSync(secretsFile(dir, repo), 0o600);
+    return { ok: true, said: trimmed === "" ? `Removed ${name}.` : `Saved ${name}. Only this project's web requests and scripts that name it get it.` };
+}

package/dist/flow-sort.d.ts

@@ -0,0 +1,82 @@
+import { type FlowSort, type FlowStage } from "./flows.js";
+export declare const JEV_URL = "https://openrouter.ai/api/alpha/decisions";
+export declare const JEV_MODEL = "~typesafe/jev-latest";
+export type SortNoteAnswer = {
+    id: string;
+    question: string;
+    kind: "score" | "yes-no";
+    answer: string;
+    sure: number;
+};
+/** What a sort step decided, kept on its run (decision_json) and shown on the card. */
+export type SortDecision = {
+    model: string;
+    /** The answer as the zone names it, and how sure Jev was (0–1). */
+    answer: string;
+    sure: number;
+    sureAt: number;
+    /** Sure enough to act alone, and where the card went (null: it waited in the zone). */
+    confident: boolean;
+    to: string | null;
+    /** Every answer's chance, by name. */
+    chances: Record<string, number>;
+    notes: SortNoteAnswer[];
+    cost: number | null;
+    ms: number;
+};
+export type SortCard = {
+    title: string;
+    description: string | null;
+    note: string | null;
+    outputs: Record<string, string>;
+    source: {
+        label: string;
+    } | null;
+};
+type Question = {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+} | {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+} | {
+    type: "noul";
+    instructions: string;
+};
+export type JevRequest = {
+    model: string;
+    state: Record<string, string>;
+    questions: Record<string, Question>;
+};
+/** What Jev reads: the card, where it came from, the latest note and what earlier zones reported — bounded, keys blanked. */
+export declare function sortState(card: SortCard, earlier: readonly {
+    id: string;
+    title: string;
+}[]): Record<string, string>;
+/** The one request for a card: the zone's question over its answers, plus what it also notes. */
+export declare function sortRequest(sort: FlowSort, state: Record<string, string>): JevRequest;
+export type JevAsked = {
+    ok: true;
+    body: Record<string, unknown>;
+    ms: number;
+} | {
+    ok: false;
+    said: string;
+};
+/** Ask Jev through OpenRouter. Trouble reaching it (or a refused key, or no credit) is a reason to try again, in words. */
+export declare function askJev(fetcher: typeof fetch, key: string, request: JevRequest): Promise<JevAsked>;
+/** Jev's answers, read back against the zone's own options only; anything else is a problem, never a route. */
+export declare function readJevAnswers(stage: FlowStage, body: Record<string, unknown>, ms: number): SortDecision | {
+    problem: string;
+};
+/** The decision in one line, as the card and later zones read it ({{stage.<id>}}). */
+export declare function sortWords(decision: SortDecision): string;
+/** The run's log: every answer's chance and each note, for the Insights run view. */
+export declare function sortLog(stage: FlowStage, decision: SortDecision): string;
+/** A kept decision, or null when there is none or it can't be read. */
+export declare function parseSortDecision(json: string | null): SortDecision | null;
+/** A card's chip on the canvas: the answer and how sure, and the first score's short level. */
+export declare function sortChip(decision: SortDecision): string;
+export {};

package/dist/flow-sort.js

@@ -0,0 +1,153 @@
+/**
+ * Sort steps (v85): Jev, TypeSafe's decision model, reached through
+ * OpenRouter's Decisions API with the operator's own OpenRouter key. One
+ * request per card: the card is the `state`; the zone's question is a
+ * choice over its answers, and each thing the zone also notes is a score
+ * or a yes/no question in the same request. Jev answers in well under a
+ * second, with how sure it is. It never writes text, so nothing it returns
+ * is instructions: an answer is only ever one of the zone's own options.
+ */
+import { redactSecretLines, scanForSecrets } from "./evidence.js";
+import { sortKeyOf } from "./flows.js";
+export const JEV_URL = "https://openrouter.ai/api/alpha/decisions";
+export const JEV_MODEL = "~typesafe/jev-latest";
+/** Jev reads up to 32,000 tokens; the card is kept well under that. */
+const STATE_CHARS = 40_000;
+const clip = (text, cap) => text.length <= cap ? text : `${text.slice(0, cap - 1)}…`;
+/** Key-shaped lines never leave the machine. */
+const blank = (text) => redactSecretLines(text, scanForSecrets(text));
+/** What Jev reads: the card, where it came from, the latest note and what earlier zones reported — bounded, keys blanked. */
+export function sortState(card, earlier) {
+    const state = { title: blank(clip(card.title, 500)) };
+    if (card.description !== null && card.description.trim() !== "")
+        state["details"] = blank(clip(card.description, 20_000));
+    if (card.source !== null)
+        state["came_from"] = clip(card.source.label, 200);
+    if (card.note !== null && card.note.trim() !== "")
+        state["latest_note"] = blank(clip(card.note, 2000));
+    let room = STATE_CHARS - Object.values(state).reduce((sum, one) => sum + one.length, 0);
+    for (const zone of earlier) {
+        const said = card.outputs[zone.id];
+        if (said === undefined || said.trim() === "" || room < 200)
+            continue;
+        const kept = blank(clip(said, Math.min(8000, room)));
+        state[`notes_from_${zone.id.replace(/-/g, "_")}`] = kept;
+        room -= kept.length;
+    }
+    return state;
+}
+/** The one request for a card: the zone's question over its answers, plus what it also notes. */
+export function sortRequest(sort, state) {
+    const questions = {
+        route: { type: "choice", instructions: `${sort.question} Read the card's title and details.`, criteria: Object.fromEntries(sort.answers.map(one => [sortKeyOf(one.answer), one.means])) },
+    };
+    for (const note of sort.notes) {
+        questions[`note_${note.id.replace(/-/g, "_")}`] = note.kind === "score" && note.levels !== null
+            ? { type: "score", instructions: note.question, criteria: note.levels }
+            : { type: "noul", instructions: note.question };
+    }
+    return { model: JEV_MODEL, state, questions };
+}
+/** Ask Jev through OpenRouter. Trouble reaching it (or a refused key, or no credit) is a reason to try again, in words. */
+export async function askJev(fetcher, key, request) {
+    const started = Date.now();
+    let response;
+    try {
+        response = await fetcher(JEV_URL, {
+            method: "POST",
+            headers: { authorization: `Bearer ${key}`, "content-type": "application/json", "x-title": "Toolroll" },
+            body: JSON.stringify(request), signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch {
+        return { ok: false, said: "Couldn't reach OpenRouter." };
+    }
+    let body = {};
+    try {
+        body = await response.json();
+    }
+    catch { /* said below */ }
+    if (!response.ok) {
+        const error = body["error"];
+        const detail = typeof error?.message === "string" ? ` It said: ${clip(error.message.replace(/\s+/g, " "), 160)}` : "";
+        const said = response.status === 401 || response.status === 403 ? "OpenRouter didn't accept the key. Check it in Settings → AI providers."
+            : response.status === 402 ? "OpenRouter says the account is out of credit."
+                : response.status === 404 ? "OpenRouter couldn't find Jev for this key."
+                    : response.status === 429 ? "OpenRouter asked us to slow down."
+                        : `OpenRouter answered with an error (${response.status}).`;
+        return { ok: false, said: `${said}${detail}` };
+    }
+    return { ok: true, body, ms: Date.now() - started };
+}
+const shortLevel = (level) => level.split(":")[0].trim();
+/** Jev's answers, read back against the zone's own options only; anything else is a problem, never a route. */
+export function readJevAnswers(stage, body, ms) {
+    const sort = stage.sort;
+    const answers = body["answers"];
+    const route = answers?.["route"];
+    if (route === undefined || typeof route["choice"] !== "string")
+        return { problem: "Jev's answer didn't say which way to go." };
+    const picked = sort.answers.find(one => sortKeyOf(one.answer) === route["choice"]);
+    if (picked === undefined)
+        return { problem: "Jev picked an answer this zone doesn't have." };
+    const number = (value) => typeof value === "number" && Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
+    const sure = number(route["confidence"]);
+    const probabilities = (route["probabilities"] ?? {});
+    const chances = Object.fromEntries(sort.answers.map(one => [one.answer, Math.round(number(probabilities[sortKeyOf(one.answer)]) * 100) / 100]));
+    const notes = [];
+    for (const note of sort.notes) {
+        const said = answers?.[`note_${note.id.replace(/-/g, "_")}`];
+        if (said === undefined)
+            continue;
+        if (note.kind === "score" && note.levels !== null && typeof said["score"] === "number") {
+            const level = note.levels[Math.min(note.levels.length - 1, Math.max(0, Math.round(said["score"])))];
+            notes.push({ id: note.id, question: note.question, kind: "score", answer: level, sure: Math.round(number(said["confidence"]) * 100) / 100 });
+        }
+        else if (typeof said["noul"] === "number") {
+            const yes = number(said["noul"]);
+            notes.push({ id: note.id, question: note.question, kind: "yes-no", answer: yes >= 0.5 ? "yes" : "no", sure: Math.round(Math.max(yes, 1 - yes) * 100) / 100 });
+        }
+    }
+    const confident = sure >= sort.sureAt;
+    const usage = body["usage"];
+    return {
+        model: typeof body["model"] === "string" ? body["model"] : JEV_MODEL,
+        answer: picked.answer, sure: Math.round(sure * 100) / 100, sureAt: sort.sureAt,
+        confident, to: confident ? picked.to : stage.onFail, chances, notes,
+        cost: typeof usage?.cost === "number" ? usage.cost : null, ms,
+    };
+}
+const percent = (value) => `${Math.round(value * 100)}%`;
+/** The decision in one line, as the card and later zones read it ({{stage.<id>}}). */
+export function sortWords(decision) {
+    const lead = decision.confident ? `${decision.answer}, ${percent(decision.sure)} sure.` : `Not sure: ${percent(decision.sure)} ${decision.answer}.`;
+    const notes = decision.notes.map(one => one.kind === "score" ? `${one.question} ${shortLevel(one.answer)}.` : `${one.question} ${one.answer === "yes" ? "Yes" : "No"}.`);
+    return [lead, ...notes].join(" ");
+}
+/** The run's log: every answer's chance and each note, for the Insights run view. */
+export function sortLog(stage, decision) {
+    const lines = [`Jev (${decision.model}) · ${decision.ms} ms${decision.cost === null ? "" : ` · $${decision.cost.toFixed(6)}`}`, "", stage.sort.question];
+    for (const [answer, chance] of Object.entries(decision.chances).sort((a, b) => b[1] - a[1]))
+        lines.push(`  ${answer.padEnd(24)} ${percent(chance).padStart(4)}${answer === decision.answer ? "  ← picked" : ""}`);
+    lines.push(`  Sure: ${percent(decision.sure)} (acts alone from ${percent(decision.sureAt)})`);
+    for (const note of decision.notes)
+        lines.push("", note.question, `  ${note.answer} (${percent(note.sure)} sure)`);
+    return lines.join("\n");
+}
+/** A kept decision, or null when there is none or it can't be read. */
+export function parseSortDecision(json) {
+    if (json === null)
+        return null;
+    try {
+        const value = JSON.parse(json);
+        return typeof value.answer === "string" && typeof value.sure === "number" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A card's chip on the canvas: the answer and how sure, and the first score's short level. */
+export function sortChip(decision) {
+    const score = decision.notes.find(one => one.kind === "score");
+    return [`${decision.answer} · ${percent(decision.sure)}`, ...(score === undefined ? [] : [shortLevel(score.answer)])].join(" · ");
+}

package/dist/flow-steps.d.ts

@@ -0,0 +1,40 @@
+import type { Runner } from "./backend.js";
+import { type DraftRunner } from "./flow-draft.js";
+import { type MailSender, type ToolCaller } from "./flow-actions.js";
+import type { Store } from "./store.js";
+import type { TurnRunner } from "./teammates.js";
+import type { ToolLister } from "./teammate-tools.js";
+export type StepIo = {
+    /** `gh` for GitHub; git and the check's shell, both without a model. */
+    gh: Runner;
+    git: Runner;
+    shell: Runner;
+    fetch: typeof fetch;
+    /** Beside the database: the Linear key. */
+    dir: string | null;
+    /** Where temporary copies of a card's work are made. */
+    scratch: string;
+    evidenceRoot?: string;
+    /** The branch a card with no result yet is checked against. */
+    base: string;
+    /** The operator's OpenRouter key, for sort steps (default: the one stored in Settings → AI providers). */
+    openRouterKey?: () => string | null;
+    /** Writes a draft (default: Claude through this computer's sign-in, no tools). */
+    draft?: DraftRunner;
+    /** Sends an email (default: the mail server in Settings → Email). */
+    mail?: MailSender;
+    /** Calls a project tool (default: starts its MCP server, like its Test button). */
+    callTool?: ToolCaller;
+    /** Where the project tools' secrets live (default: this computer's home). */
+    toolHome?: string;
+    /** Takes a teammate's turn (default: Claude through this computer's sign-in, answering in its fixed shape). */
+    teammate?: TurnRunner;
+    /** Lists what a project tool offers a teammate (default: starts its MCP server and asks). */
+    listTools?: ToolLister;
+};
+export type StepPass = {
+    ran: number;
+    problems: string[];
+};
+/** Run every due check and update in one project, then move each card on. */
+export declare function runFlowSteps(store: Store, repo: string, now: Date, io: StepIo): Promise<StepPass>;