toolroll 0.9.94 → 0.9.96

package/dist/card-catalog.d.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+export declare const CARD_SOURCES: readonly ["tasks", "results", "flows", "flow_zones", "spend", "projects", "builders", "mode", "integrations", "providers", "findings", "handover"];
+export type CardSourceName = (typeof CARD_SOURCES)[number];
+export declare const CARD_TASK_STATES: readonly ["queued", "running", "done", "failed", "cancelled"];
+export declare const CARD_CATALOG: import("@json-render/core").Catalog<{
+    spec: import("@json-render/core").SchemaType<"object", {
+        root: import("@json-render/core").SchemaType<"string", unknown>;
+        elements: import("@json-render/core").SchemaType<"record", import("@json-render/core").SchemaType<"object", {
+            type: import("@json-render/core").SchemaType<"ref", string>;
+            props: import("@json-render/core").SchemaType<"propsOf", string>;
+            children: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
+        }>>;
+    }>;
+    catalog: import("@json-render/core").SchemaType<"object", {
+        components: import("@json-render/core").SchemaType<"map", {
+            props: import("@json-render/core").SchemaType<"zod", unknown>;
+            description: import("@json-render/core").SchemaType<"string", unknown>;
+        }>;
+    }>;
+}, {
+    components: {
+        Card: {
+            props: z.ZodObject<{}, z.core.$strict>;
+            description: string;
+        };
+        Text: {
+            props: z.ZodObject<{
+                text: z.ZodString;
+            }, z.core.$strict>;
+            description: string;
+        };
+        Fields: {
+            props: z.ZodObject<{
+                repo: z.ZodOptional<z.ZodString>;
+                task: z.ZodOptional<z.ZodString>;
+                state: z.ZodOptional<z.ZodEnum<{
+                    cancelled: "cancelled";
+                    done: "done";
+                    failed: "failed";
+                    queued: "queued";
+                    running: "running";
+                }>>;
+                limit: z.ZodOptional<z.ZodInt>;
+                flow: z.ZodOptional<z.ZodInt>;
+                days: z.ZodOptional<z.ZodInt>;
+                source: z.ZodEnum<{
+                    builders: "builders";
+                    findings: "findings";
+                    flow_zones: "flow_zones";
+                    flows: "flows";
+                    handover: "handover";
+                    integrations: "integrations";
+                    mode: "mode";
+                    projects: "projects";
+                    providers: "providers";
+                    results: "results";
+                    spend: "spend";
+                    tasks: "tasks";
+                }>;
+                facts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+            description: string;
+        };
+        Table: {
+            props: z.ZodObject<{
+                repo: z.ZodOptional<z.ZodString>;
+                task: z.ZodOptional<z.ZodString>;
+                state: z.ZodOptional<z.ZodEnum<{
+                    cancelled: "cancelled";
+                    done: "done";
+                    failed: "failed";
+                    queued: "queued";
+                    running: "running";
+                }>>;
+                limit: z.ZodOptional<z.ZodInt>;
+                flow: z.ZodOptional<z.ZodInt>;
+                days: z.ZodOptional<z.ZodInt>;
+                source: z.ZodEnum<{
+                    builders: "builders";
+                    findings: "findings";
+                    flow_zones: "flow_zones";
+                    flows: "flows";
+                    handover: "handover";
+                    integrations: "integrations";
+                    mode: "mode";
+                    projects: "projects";
+                    providers: "providers";
+                    results: "results";
+                    spend: "spend";
+                    tasks: "tasks";
+                }>;
+                columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+            description: string;
+        };
+        Notes: {
+            props: z.ZodObject<{
+                repo: z.ZodOptional<z.ZodString>;
+                task: z.ZodOptional<z.ZodString>;
+                state: z.ZodOptional<z.ZodEnum<{
+                    cancelled: "cancelled";
+                    done: "done";
+                    failed: "failed";
+                    queued: "queued";
+                    running: "running";
+                }>>;
+                limit: z.ZodOptional<z.ZodInt>;
+                flow: z.ZodOptional<z.ZodInt>;
+                days: z.ZodOptional<z.ZodInt>;
+                source: z.ZodEnum<{
+                    builders: "builders";
+                    findings: "findings";
+                    flow_zones: "flow_zones";
+                    flows: "flows";
+                    handover: "handover";
+                    integrations: "integrations";
+                    mode: "mode";
+                    projects: "projects";
+                    providers: "providers";
+                    results: "results";
+                    spend: "spend";
+                    tasks: "tasks";
+                }>;
+            }, z.core.$strict>;
+            description: string;
+        };
+        Chart: {
+            props: z.ZodObject<{
+                repo: z.ZodOptional<z.ZodString>;
+                task: z.ZodOptional<z.ZodString>;
+                state: z.ZodOptional<z.ZodEnum<{
+                    cancelled: "cancelled";
+                    done: "done";
+                    failed: "failed";
+                    queued: "queued";
+                    running: "running";
+                }>>;
+                limit: z.ZodOptional<z.ZodInt>;
+                flow: z.ZodOptional<z.ZodInt>;
+                days: z.ZodOptional<z.ZodInt>;
+                source: z.ZodEnum<{
+                    builders: "builders";
+                    findings: "findings";
+                    flow_zones: "flow_zones";
+                    flows: "flows";
+                    handover: "handover";
+                    integrations: "integrations";
+                    mode: "mode";
+                    projects: "projects";
+                    providers: "providers";
+                    results: "results";
+                    spend: "spend";
+                    tasks: "tasks";
+                }>;
+                chart: z.ZodEnum<{
+                    area: "area";
+                    bar: "bar";
+                    line: "line";
+                    pie: "pie";
+                }>;
+            }, z.core.$strict>;
+            description: string;
+        };
+        Divider: {
+            props: z.ZodObject<{}, z.core.$strict>;
+            description: string;
+        };
+        Actions: {
+            props: z.ZodObject<{}, z.core.$strict>;
+            description: string;
+        };
+        Button: {
+            props: z.ZodObject<{
+                control: z.ZodOptional<z.ZodEnum<{
+                    [x: string]: string;
+                }>>;
+                task: z.ZodOptional<z.ZodString>;
+                run: z.ZodOptional<z.ZodInt>;
+                repo: z.ZodOptional<z.ZodString>;
+                proposal: z.ZodOptional<z.ZodInt>;
+            }, z.core.$strict>;
+            description: string;
+        };
+    };
+}>;
+export type CardComponent = keyof typeof CARD_CATALOG.data.components;
+export type CardElement = {
+    type: CardComponent;
+    props: Record<string, unknown>;
+    children: string[];
+};
+/** A checked spec, as the parts of its card in order. */
+export type CardPlan = {
+    parts: {
+        type: CardComponent;
+        props: Record<string, unknown>;
+    }[];
+    buttons: Record<string, unknown>[];
+};
+/** A spec as a card plan, or every reason it isn't one, in words the lead can fix on its next step. */
+export declare function readCardSpec(raw: unknown): {
+    ok: true;
+    plan: CardPlan;
+} | {
+    ok: false;
+    issues: string[];
+};
+/** The catalog in words, for the lead's tool description: json-render's full prompt describes features a card refuses. */
+export declare function cardCatalogWords(): string;

package/dist/card-catalog.js

@@ -0,0 +1,133 @@
+/**
+ * What a lead may put on a card (docs/plans/toolroll-cards.md): a json-render spec limited to this catalog.
+ *
+ * json-render defines the catalog and checks a spec's structure. Its own check lets any props through when a catalog has
+ * several components, so each element's props are read here, strictly, against its component. json-render's dynamic
+ * features ($state, repeat, visible, on) are refused: a card is data Toolroll fills, not a program.
+ *
+ * Nothing here can carry a figure or an address. Fields, Table and Chart name a source; Text is the one free field.
+ */
+import { defineCatalog, defineSchema, validateSpec } from "@json-render/core";
+import { z } from "zod";
+import { CHAT_CONTROLS } from "./chat-controls.js";
+import { CARD_CHART_TYPES, CARD_LIMITS } from "./contracts/chat-card.js";
+export const CARD_SOURCES = ["tasks", "results", "flows", "flow_zones", "spend", "projects", "builders", "mode", "integrations", "providers", "findings", "handover"];
+export const CARD_TASK_STATES = ["queued", "running", "done", "failed", "cancelled"];
+const source = z.enum(CARD_SOURCES);
+const repo = z.string().regex(/^r[0-9]{1,3}$/);
+const pick = z.array(z.string().max(40)).min(1).max(CARD_LIMITS.columns);
+/** What narrows a source: read by the sources, which check each against who is asking. */
+const narrowing = { repo: repo.optional(), task: z.string().max(200).optional(), state: z.enum(CARD_TASK_STATES).optional(), limit: z.int().min(1).max(CARD_LIMITS.rows).optional(), flow: z.int().min(1).optional(), days: z.int().min(1).max(90).optional() };
+const schema = defineSchema(s => ({
+    spec: s.object({
+        root: s.string(),
+        elements: s.record(s.object({ type: s.ref("catalog.components"), props: s.propsOf("catalog.components"), children: s.array(s.string()) })),
+    }),
+    catalog: s.object({ components: s.map({ props: s.zod(), description: s.string() }) }),
+}));
+export const CARD_CATALOG = defineCatalog(schema, {
+    components: {
+        Card: { props: z.strictObject({}), description: "The root. Its children are the card's parts in order. Its title comes from its first source." },
+        Text: { props: z.strictObject({ text: z.string().min(1).max(CARD_LIMITS.text) }), description: "Your own words, shown as a plain paragraph. Never a place for figures you want read as records." },
+        Fields: { props: z.strictObject({ source, facts: z.array(z.string().max(40)).min(1).max(CARD_LIMITS.facts).optional(), ...narrowing }), description: "Key facts from a source, filled by Toolroll. facts picks which." },
+        Table: { props: z.strictObject({ source, columns: pick.optional(), ...narrowing }), description: "Rows from a source, filled by Toolroll. columns picks which." },
+        Notes: { props: z.strictObject({ source, ...narrowing }), description: "Saved words from a source, whole, one to a line: findings or handover (with task)." },
+        Chart: { props: z.strictObject({ source, chart: z.enum(CARD_CHART_TYPES), ...narrowing }), description: "A chart of a source's numbers, filled by Toolroll: bar, pie, line or area." },
+        Divider: { props: z.strictObject({}), description: "A line between parts." },
+        Actions: { props: z.strictObject({}), description: "Holds the card's Buttons." },
+        Button: {
+            props: z.strictObject({ control: z.enum(Object.keys(CHAT_CONTROLS)).optional(), task: z.string().max(200).optional(), run: z.int().min(1).optional(), repo: repo.optional(), proposal: z.int().min(1).optional() }),
+            description: "control opens a fixed Toolroll page (as show_control). proposal points at one you proposed earlier this reply; its Confirm stays on its own message under the card.",
+        },
+    },
+});
+const issues = (lines) => ({ ok: false, issues: lines });
+/** A spec as a card plan, or every reason it isn't one, in words the lead can fix on its next step. */
+export function readCardSpec(raw) {
+    const shape = CARD_CATALOG.validate(raw);
+    if (!shape.success)
+        return issues((shape.error?.issues ?? []).map(one => `${one.path.join(".")}: ${one.message}`));
+    const spec = raw;
+    const structure = validateSpec(spec, { checkOrphans: true });
+    const refused = structure.issues.map(one => one.message);
+    if (refused.length > 0)
+        return issues(refused);
+    const parsed = new Map();
+    for (const key of Object.keys(spec.elements)) {
+        const element = spec.elements[key];
+        const extra = Object.keys(element).filter(one => one !== "type" && one !== "props" && one !== "children");
+        if (extra.length > 0) {
+            refused.push(`${key}: a card element has only type, props and children, not ${extra.join(", ")}`);
+            continue;
+        }
+        const type = element["type"];
+        const props = CARD_CATALOG.data.components[type].props.safeParse(element["props"]);
+        if (!props.success) {
+            refused.push(...props.error.issues.map(one => `${key}.props.${one.path.join(".")}: ${one.message}`));
+            continue;
+        }
+        parsed.set(key, { type, props: props.data, children: element["children"] });
+    }
+    if (refused.length > 0)
+        return issues(refused);
+    const own = (key) => Object.hasOwn(spec.elements, key) ? parsed.get(key) : undefined;
+    const root = own(spec.root);
+    if (root?.type !== "Card")
+        return issues(["root: the root must be a Card"]);
+    const seen = new Set([spec.root]);
+    const plan = { parts: [], buttons: [] };
+    const used = (key) => {
+        const element = own(key);
+        if (element === undefined) {
+            refused.push(`${key}: no such element`);
+            return null;
+        }
+        if (seen.has(key)) {
+            refused.push(`${key}: an element appears once`);
+            return null;
+        }
+        seen.add(key);
+        return element;
+    };
+    for (const key of root.children) {
+        const element = used(key);
+        if (element === null)
+            continue;
+        if (element.type === "Actions") {
+            for (const inner of element.children) {
+                const button = used(inner);
+                if (button === null)
+                    continue;
+                if (button.type !== "Button")
+                    refused.push(`${inner}: Actions holds Buttons`);
+                else if ((button.props["control"] === undefined) === (button.props["proposal"] === undefined))
+                    refused.push(`${inner}: a Button names a control or a proposal, one of them`);
+                else
+                    plan.buttons.push(button.props);
+            }
+            continue;
+        }
+        if (element.type === "Card" || element.type === "Button") {
+            refused.push(`${key}: a ${element.type} can't be a part of a card`);
+            continue;
+        }
+        if (element.children.length > 0) {
+            refused.push(`${key}: a ${element.type} has no children`);
+            continue;
+        }
+        plan.parts.push({ type: element.type, props: element.props });
+    }
+    if (seen.size !== parsed.size)
+        refused.push("every element must be reached from the root");
+    if (plan.parts.length > CARD_LIMITS.blocks)
+        refused.push(`a card has at most ${CARD_LIMITS.blocks} parts`);
+    if (plan.buttons.length > CARD_LIMITS.buttons + CARD_LIMITS.actions)
+        refused.push("too many Buttons");
+    if (!plan.parts.some(one => one.type === "Fields" || one.type === "Table" || one.type === "Notes" || one.type === "Chart"))
+        refused.push("a card shows data: give it Fields, a Table, Notes or a Chart. For words alone, just reply");
+    return refused.length > 0 ? issues(refused) : { ok: true, plan };
+}
+/** The catalog in words, for the lead's tool description: json-render's full prompt describes features a card refuses. */
+export function cardCatalogWords() {
+    return Object.entries(CARD_CATALOG.data.components).map(([name, one]) => `${name}: ${one.description}`).join(" ");
+}

package/dist/card-cli.d.ts

@@ -0,0 +1,43 @@
+import type { Store } from "./store.js";
+export declare const CARD_DESCRIPTOR: {
+    invocation: string;
+    synopsis: string;
+    flags: readonly [{
+        readonly name: "repo";
+        readonly takesValue: true;
+        readonly meaning: "one project; default: all of yours";
+    }, {
+        readonly name: "task";
+        readonly takesValue: true;
+        readonly meaning: "findings and handover: the task";
+    }, {
+        readonly name: "state";
+        readonly takesValue: true;
+        readonly meaning: "tasks: queued, running, done, failed or cancelled";
+    }, {
+        readonly name: "limit";
+        readonly takesValue: true;
+        readonly meaning: "how many rows, up to 20";
+    }, {
+        readonly name: "flow";
+        readonly takesValue: true;
+        readonly meaning: "flow_zones: the flow's number";
+    }, {
+        readonly name: "days";
+        readonly takesValue: true;
+        readonly meaning: "flow_zones: how far back, up to 90";
+    }];
+};
+export type CardCliContext = {
+    store: Store;
+    write: (line: string) => void;
+    json: boolean;
+    now: Date;
+    actor: string | null;
+    repos: readonly string[];
+    evidenceRoot?: string;
+    /** The CLI's own envelope (operate.ts succeed/fail): one JSON document under --json, plain lines otherwise. */
+    ok: (result: Record<string, unknown>, lines: () => string[]) => number;
+    no: (reason: string, message: string) => number;
+};
+export declare function runCardCommand(positional: readonly string[], options: ReadonlyMap<string, string | true>, context: CardCliContext): number;

package/dist/card-cli.js

@@ -0,0 +1,44 @@
+/** `toolroll card <source>` (docs/plans/toolroll-cards.md): the card chat shows, from the same records, on the command line. */
+import { CARD_SOURCES } from "./card-catalog.js";
+import { cardPlainText } from "./card-render.js";
+import { readCardSource } from "./card-sources.js";
+import { buildChatCard } from "./chat-card.js";
+import { capabilitiesOf } from "./lead-capabilities.js";
+const flags = [
+    { name: "repo", takesValue: true, meaning: "one project; default: all of yours" },
+    { name: "task", takesValue: true, meaning: "findings and handover: the task" },
+    { name: "state", takesValue: true, meaning: "tasks: queued, running, done, failed or cancelled" },
+    { name: "limit", takesValue: true, meaning: "how many rows, up to 20" },
+    { name: "flow", takesValue: true, meaning: "flow_zones: the flow's number" },
+    { name: "days", takesValue: true, meaning: "flow_zones: how far back, up to 90" },
+];
+export const CARD_DESCRIPTOR = { invocation: "card", synopsis: `show Toolroll's own data as chat's cards do: ${CARD_SOURCES.join(", ")} (read only)`, flags };
+export function runCardCommand(positional, options, context) {
+    const fail = (reason, message) => context.no(reason, message);
+    const source = positional[0];
+    if (source === undefined || !CARD_SOURCES.includes(source))
+        return fail("usage", `Use card <${CARD_SOURCES.join("|")}> [--repo PATH] [--task ID] [--state S] [--limit N] [--flow N] [--days N].`);
+    if (context.actor === null)
+        return fail("unauthenticated", "Sign in first: the remembered local login drives card.");
+    const { store, now } = context, actor = context.actor;
+    const capabilities = (repos) => capabilitiesOf(store, { repos, admitted: context.repos, actor, integrations: [], now });
+    const reader = { store, now, who: { name: actor, repos: context.repos }, ...(context.evidenceRoot === undefined ? {} : { evidenceRoot: context.evidenceRoot }),
+        providers: repos => capabilities(repos).projects.flatMap(one => one.agents.map(agent => ({ project: one.repo, provider: agent.provider, model: agent.model, roles: agent.roles, state: agent.state }))),
+        workers: repos => capabilities(repos).workers.map(one => ({ name: one.name, state: one.state, capacity: one.capacity, running: one.running.length })) };
+    const value = (name) => { const got = options.get(name); return typeof got === "string" ? got : undefined; };
+    const number = (name) => { const got = Number(value(name)); return value(name) === undefined || !Number.isSafeInteger(got) || got < 1 ? {} : { [name]: got }; };
+    const props = { source, ...(value("repo") === undefined ? {} : { repo: value("repo") }), ...(value("task") === undefined ? {} : { task: value("task") }), ...(value("state") === undefined ? {} : { state: value("state") }), ...number("limit"), ...number("flow"), ...number("days") };
+    const read = readCardSource(reader, source, { repo: value("repo") ?? null, ...(value("task") === undefined ? {} : { task: value("task") }), ...(value("state") === undefined ? {} : { state: value("state") }), ...number("limit"), ...number("flow"), ...number("days") });
+    if ("problem" in read)
+        return fail("refused", read.problem);
+    const plan = { buttons: [], parts: [
+            ...(read.facts.length === 0 ? [] : [{ type: "Fields", props }]),
+            { type: "Table", props },
+            ...(read.notes === undefined || read.notes.length === 0 ? [] : [{ type: "Notes", props }]),
+            ...(read.points.length === 0 ? [] : [{ type: "Chart", props: { ...props, chart: "bar" } }]),
+        ] };
+    const built = buildChatCard(reader, plan, id => typeof id === "string" ? id : null, () => ({ ok: true }));
+    if (!built.ok)
+        return fail("refused", built.message);
+    return context.ok({ card: built.card }, () => cardPlainText(built.card).split("\n"));
+}

package/dist/card-render.d.ts

@@ -0,0 +1,43 @@
+/**
+ * One card, in each app's own form (docs/plans/toolroll-cards.md). A card's values are already scrubbed; here they are
+ * made inert for each app, so a value can't become a link, a mention or formatting. Whatever an app can't show comes out
+ * as readable text, and every renderer has the same plain version to fall back on.
+ */
+import type { ChatCard, ChatCardBlock } from "./contracts/chat-card.js";
+import { type Html } from "./html.js";
+type Table = Extract<ChatCardBlock, {
+    kind: "table";
+}>;
+/** A Text part is the lead's (a model's) words: always labelled as such, on every app, never as a record. */
+export declare const LEAD_NOTE_WORDS = "The lead's note, not Toolroll's records";
+/** The whole card as plain text: the version every app can show. */
+export declare function cardPlainText(card: ChatCard): string;
+/** The card as Block Kit, native where Slack has it: one data table and two charts a message, the rest as code blocks. */
+export declare function slackCardBlocks(card: ChatCard, buttons: readonly Record<string, unknown>[]): Record<string, unknown>[];
+/** The card as one embed: facts as fields, tables and charts as code blocks. `plain` escapes Discord's own syntax. */
+export declare function discordCardEmbed(card: ChatCard, plain: (text: string) => string): Record<string, unknown>;
+/** The card as one Telegram message: plain words, tables and charts as `pre` entities, so nothing in a value is parsed. */
+export declare function telegramCardMessage(card: ChatCard): {
+    text: string;
+    entities: {
+        type: "pre" | "bold";
+        offset: number;
+        length: number;
+    }[];
+};
+/** The card as the web chat's own markup; every value is escaped by `html`. */
+export declare function webCardHtml(card: ChatCard): Html;
+/**
+ * A table's rows for a phone: each row's first value in full as its name, then its other values on one line ("queued ·
+ * standing-orders · 3h ago"; a number keeps its column's label: "Failed attempts 2"). A column with the same value in
+ * every shown row is said once above the rows instead ("All: queued · Failed attempts 0").
+ */
+export declare function telegramTableRows(block: Table, keep: number): {
+    same: string;
+    rows: {
+        name: string;
+        rest: string;
+    }[];
+    more: number;
+};
+export {};