toolroll 0.5.0

package/dist/teammate-tools.d.ts

@@ -0,0 +1,108 @@
+import type { ToolCaller } from "./flow-actions.js";
+import { type ProjectTool, type ToolSpec } from "./project-tools.js";
+import type { Store, TeammateCallRow, TeammateGrantRow, TeammateRow, ToolActionInfo, ToolRule } from "./store.js";
+/** Lists what a tool offers; injectable so tests never start a server. */
+export type ToolLister = (spec: ToolSpec, values: Record<string, string>) => Promise<{
+    ok: true;
+    actions: ToolActionInfo[];
+} | {
+    ok: false;
+    problem: string;
+}>;
+export type ToolIo = {
+    callTool?: ToolCaller;
+    listTools?: ToolLister;
+    toolHome?: string;
+};
+/** Actions whose names say they only read start as "do it"; everything else asks first until its manager says otherwise. */
+export declare const READ_VERB: RegExp;
+export declare const defaultRule: (action: Pick<ToolActionInfo, "name" | "readOnly">) => ToolRule;
+type Done = {
+    ok: true;
+    said: string;
+} | {
+    ok: false;
+    said: string;
+};
+/** How a turn names an action: "shop.refund_order". */
+export declare const callName: (tool: string, action: string) => string;
+/** A fresh listing merged into a grant: rules already set are kept, new actions get the default, and gone ones drop out. */
+export declare function withActions(rules: Record<string, ToolRule>, actions: readonly ToolActionInfo[]): {
+    actions: ToolActionInfo[];
+    rules: Record<string, ToolRule>;
+};
+/** The rule that applies to one call with this input, and why, in words. */
+export declare function ruleFor(grant: Pick<TeammateGrantRow, "actions" | "rules">, action: string, input: Record<string, unknown>): {
+    use: ToolRule["use"];
+    why: string;
+};
+/** A rule in words, for the teammate's turn and its page. */
+export declare function ruleWords(rule: ToolRule): string;
+/** Number fields an action's input declares: what a limit can be set on. */
+export declare function numberFields(action: Pick<ToolActionInfo, "input">): string[];
+/** What's wrong with an input, by what the action declares: its required fields and their simple types. */
+export declare function inputProblem(action: Pick<ToolActionInfo, "input">, input: Record<string, unknown>): string | null;
+/** A call in a few words: "shop → refund_order · order 1044 · amount 400". */
+export declare function callWords(tool: string, action: string, input: Record<string, unknown>, cap?: number): string;
+/** An action as a turn is offered it. */
+export type OfferedTool = {
+    name: string;
+    about: string;
+    input: string;
+    rule: string;
+};
+/** What a teammate may use now: its grants' actions on tools the project still has, "never" left out. */
+export declare function offeredTools(store: Store, mate: TeammateRow): OfferedTool[];
+/** Before a turn: re-list tools whose listing is old (or never happened), so the turn sees what they offer today. A tool that can't be reached keeps its last listing. */
+export declare function refreshGrants(store: Store, mate: TeammateRow, now: Date, io: ToolIo): Promise<void>;
+/** Let a teammate use one of the project's tools. Its actions start at their defaults: reading is free, everything else asks first. */
+export declare function grantTool(store: Store, mate: TeammateRow, tool: string, by: string, now: Date, io?: ToolIo): Promise<Done>;
+/** A grant from what the tool offers (or, not reachable now, the names its last test found). */
+export declare function grantListed(store: Store, mate: TeammateRow, tool: ProjectTool, actions: ToolActionInfo[] | null, by: string, now: Date): Done;
+export declare function revokeTool(store: Store, mate: TeammateRow, tool: string, by: string, now?: Date): Done;
+/** Check one rule: an action the tool offers, a known use, and a limit on one of its number fields. */
+export declare function checkRule(grant: Pick<TeammateGrantRow, "tool" | "actions">, action: string, rule: {
+    use: unknown;
+    limit?: {
+        field: unknown;
+        over: unknown;
+    } | null;
+    undo?: unknown;
+}): {
+    ok: true;
+    rule: ToolRule;
+} | {
+    ok: false;
+    said: string;
+};
+/** Set the rules for some of a granted tool's actions; the others keep theirs. */
+export declare function setToolRules(store: Store, mate: TeammateRow, tool: string, changes: Record<string, {
+    use: unknown;
+    limit?: {
+        field: unknown;
+        over: unknown;
+    } | null;
+    undo?: unknown;
+}>, by: string, now: Date): Done;
+/**
+ * Make one call now: a free one, or one a person approved (exactly as they
+ * saw it). What the tool said is kept on the receipt, secrets scrubbed; a
+ * tool that says it failed is an answer the teammate reads, not trouble.
+ */
+export declare function makeCall(store: Store, call: TeammateCallRow, repo: string, io: ToolIo, now: Date, options?: {
+    byPerson?: boolean;
+}): Promise<TeammateCallRow>;
+/** A receipt in words: what happened to the call. */
+export declare function callOutcome(call: TeammateCallRow): string;
+/** A receipt as a person reads it on the card: what happened, and who decided. */
+export declare function receiptWords(store: Store, call: TeammateCallRow): string;
+/** The Tools section's form, read into rule changes: every action the grant knows. */
+export declare function rulesFromForm(grant: Pick<TeammateGrantRow, "actions">, field: (key: string) => string | null): Record<string, {
+    use: unknown;
+    limit?: {
+        field: unknown;
+        over: unknown;
+    };
+    undo?: unknown;
+}>;
+export {};

package/dist/teammate-tools.js

@@ -0,0 +1,271 @@
+/**
+ * The tools a teammate may use (v94), and its rule for each of their actions.
+ *
+ * A teammate never calls a tool itself. On its turn it may ask for one call
+ * ("use_tool": which action, with what input, and why), and Toolroll
+ * checks the rule its manager set for that action:
+ *
+ * - do it: the call is made and its answer goes back to the teammate, whose
+ *   turn goes on;
+ * - ask first: the exact call goes to the zone's person, in their chat app
+ *   and on the card. Approve makes exactly that call; Deny doesn't; words
+ *   tell the teammate what to do instead;
+ * - never: the action isn't offered at all.
+ *
+ * "Do it" can ask first above a number in the input ("refunds up to $50"),
+ * so a limit holds in code, not only in the soul file's words. Every call,
+ * made or not, is a receipt on the card and on the teammate's page.
+ */
+import { redactSecretLines, scanForSecrets } from "./evidence.js";
+import { scrubSecrets } from "./flow-secrets.js";
+import { toolRefusal } from "./policy.js";
+import { callProjectTool, listProjectToolActions, projectToolsOf, readToolSecrets } from "./project-tools.js";
+import { ALL_CREDENTIAL_ENV } from "./provider.js";
+/** Actions whose names say they only read start as "do it"; everything else asks first until its manager says otherwise. */
+export const READ_VERB = /^(get|list|search|find|read|fetch|lookup|look_up|query|show|describe|count|check|view|retrieve)([_.-]|$)/i;
+export const defaultRule = (action) => ({ use: action.readOnly || READ_VERB.test(action.name) ? "free" : "ask" });
+/** How long a tool's listing is trusted before a turn lists it again. */
+const LISTING_MS = 6 * 60 * 60_000;
+const RESULT_CHARS = 6000;
+/** How a turn names an action: "shop.refund_order". */
+export const callName = (tool, action) => `${tool}.${action}`;
+/** A fresh listing merged into a grant: rules already set are kept, new actions get the default, and gone ones drop out. */
+export function withActions(rules, actions) {
+    return { actions: [...actions], rules: Object.fromEntries(actions.map(one => [one.name, rules[one.name] ?? defaultRule(one)])) };
+}
+const numberOf = (value) => typeof value === "number" && Number.isFinite(value) ? value
+    : typeof value === "string" && /^\s*-?\$?\d+(\.\d+)?\s*$/.test(value) ? Number(value.replace(/[$\s]/g, "")) : null;
+/** The rule that applies to one call with this input, and why, in words. */
+export function ruleFor(grant, action, input) {
+    const info = grant.actions.find(one => one.name === action);
+    const rule = grant.rules[action] ?? (info === undefined ? { use: "never" } : defaultRule(info));
+    if (info === undefined || rule.use === "never")
+        return { use: "never", why: `The rules never allow ${action}.` };
+    if (rule.use === "ask")
+        return { use: "ask", why: `${action} needs a person's approval each time.` };
+    if (rule.limit !== undefined) {
+        const value = numberOf(input[rule.limit.field]);
+        if (value === null)
+            return { use: "ask", why: `${action} is free only up to ${rule.limit.field} ${rule.limit.over}, and this call gives no ${rule.limit.field}.` };
+        if (value > rule.limit.over)
+            return { use: "ask", why: `${rule.limit.field} ${value} is over the limit of ${rule.limit.over}.` };
+    }
+    return { use: "free", why: "" };
+}
+/** A rule in words, for the teammate's turn and its page. */
+export function ruleWords(rule) {
+    if (rule.use === "never")
+        return "never";
+    if (rule.use === "ask")
+        return "a person approves each call first";
+    return rule.limit === undefined ? "use freely" : `use freely up to ${rule.limit.field} ${rule.limit.over}; above that, a person approves first`;
+}
+/** Number fields an action's input declares: what a limit can be set on. */
+export function numberFields(action) {
+    const properties = (action.input?.["properties"] ?? {});
+    return Object.entries(properties).filter(([, one]) => one !== null && typeof one === "object" && (one.type === "number" || one.type === "integer")).map(([name]) => name).slice(0, 20);
+}
+/** What's wrong with an input, by what the action declares: its required fields and their simple types. */
+export function inputProblem(action, input) {
+    const schema = action.input;
+    if (schema === null)
+        return null;
+    const properties = (schema["properties"] ?? {});
+    const required = Array.isArray(schema["required"]) ? schema["required"].filter((one) => typeof one === "string") : [];
+    const missing = required.filter(one => input[one] === undefined || input[one] === null || input[one] === "");
+    if (missing.length > 0)
+        return `It needs ${missing.join(", ")}.`;
+    for (const [name, value] of Object.entries(input)) {
+        const type = properties[name]?.type;
+        const fits = type === undefined || typeof type !== "string" ? true
+            : type === "string" ? typeof value === "string" : type === "number" ? numberOf(value) !== null : type === "integer" ? Number.isInteger(numberOf(value))
+                : type === "boolean" ? typeof value === "boolean" : type === "array" ? Array.isArray(value) : type === "object" ? value !== null && typeof value === "object" && !Array.isArray(value) : true;
+        if (!fits)
+            return `${name} should be ${type === "integer" ? "a whole number" : `a ${type}`}.`;
+    }
+    return null;
+}
+/** A call in a few words: "shop → refund_order · order 1044 · amount 400". */
+export function callWords(tool, action, input, cap = 300) {
+    const parts = Object.entries(input).map(([key, value]) => `${key} ${typeof value === "string" ? value.replace(/\s+/g, " ") : JSON.stringify(value)}`);
+    const line = `${tool} → ${action}${parts.length === 0 ? "" : ` · ${parts.join(" · ")}`}`;
+    return line.length <= cap ? line : `${line.slice(0, cap - 1)}…`;
+}
+/** What a teammate may use now: its grants' actions on tools the project still has, "never" left out. */
+export function offeredTools(store, mate) {
+    const present = new Set(projectToolsOf(store, mate.repo).map(one => one.name));
+    // Sprint 8: a tool the organisation policy doesn't allow isn't offered.
+    const policy = store.orgPolicy();
+    return store.teammateGrants(mate.id).filter(grant => present.has(grant.tool) && toolRefusal(policy, grant.tool) === null).flatMap(grant => grant.actions.flatMap(action => {
+        const rule = grant.rules[action.name] ?? defaultRule(action);
+        if (rule.use === "never")
+            return [];
+        const input = action.input === null ? "any" : JSON.stringify({ properties: action.input["properties"] ?? {}, required: action.input["required"] ?? [] });
+        return [{ name: callName(grant.tool, action.name), about: action.about, input: input.length > 1500 ? `${input.slice(0, 1499)}…` : input, rule: ruleWords(rule) }];
+    })).slice(0, 40);
+}
+/** Before a turn: re-list tools whose listing is old (or never happened), so the turn sees what they offer today. A tool that can't be reached keeps its last listing. */
+export async function refreshGrants(store, mate, now, io) {
+    const tools = projectToolsOf(store, mate.repo);
+    for (const grant of store.teammateGrants(mate.id)) {
+        if (grant.listedAt !== null && now.getTime() - Date.parse(grant.listedAt) < LISTING_MS)
+            continue;
+        const tool = tools.find(one => one.name === grant.tool);
+        if (tool === undefined)
+            continue;
+        const listed = await listed_(tool, mate.repo, io);
+        if (!listed.ok)
+            continue;
+        store.saveTeammateGrant({ teammate: mate.id, tool: grant.tool, ...withActions(grant.rules, listed.actions), listedAt: now.toISOString() }, grant.updatedBy, now);
+    }
+}
+const listed_ = (tool, repo, io) => (io.listTools ?? ((spec, values) => listProjectToolActions(spec, values, { timeoutMs: 60_000, omitEnv: ALL_CREDENTIAL_ENV })))(tool.spec, readToolSecrets(repo, tool.name, io.toolHome));
+/** Names only, from the tool's last test: what a grant starts with when it can't be listed right now. */
+const namesOnly = (tool) => (tool.lastTest?.tools ?? []).map(name => ({ name, about: "", input: null, readOnly: false }));
+/** Let a teammate use one of the project's tools. Its actions start at their defaults: reading is free, everything else asks first. */
+export async function grantTool(store, mate, tool, by, now, io = {}) {
+    const found = projectToolsOf(store, mate.repo).find(one => one.name === tool);
+    if (found === undefined)
+        return { ok: false, said: `This project has no tool called ${tool}. Add it on the Tools page first.` };
+    if (store.teammateGrant(mate.id, tool) !== null)
+        return { ok: true, said: `It can already use ${tool}.` };
+    const listed = await listed_(found, mate.repo, io);
+    return grantListed(store, mate, found, listed.ok ? listed.actions : null, by, now);
+}
+/** A grant from what the tool offers (or, not reachable now, the names its last test found). */
+export function grantListed(store, mate, tool, actions, by, now) {
+    const offered = actions ?? namesOnly(tool);
+    if (offered.length === 0)
+        return { ok: false, said: `${tool.name} didn't say what it can do. Test it on the Tools page, then try again.` };
+    store.saveTeammateGrant({ teammate: mate.id, tool: tool.name, ...withActions({}, offered), listedAt: actions === null ? null : now.toISOString() }, by, now);
+    const free = offered.filter(one => defaultRule(one).use === "free").length;
+    return { ok: true, said: `It can use ${tool.name} now: ${free} of its ${offered.length} action${offered.length === 1 ? "" : "s"} freely (the ones that only read), and the rest after a person approves each call. Change that under Tools.` };
+}
+export function revokeTool(store, mate, tool, by, now = new Date()) {
+    for (const call of store.teammateCallsOf(mate.id, 200).filter(one => one.tool === tool && one.state === "asked")) {
+        store.moveTeammateCall(call.id, ["asked"], { state: "refused", result: `It can't use ${tool} any more.` }, new Date());
+        const question = store.teammateQuestionForCall(call.id);
+        if (question !== null)
+            store.dropTeammateQuestion(question.id, new Date());
+    }
+    return store.dropTeammateGrant(mate.id, tool, by, now) ? { ok: true, said: `It can't use ${tool} any more.` } : { ok: true, said: `It wasn't using ${tool}.` };
+}
+/** Check one rule: an action the tool offers, a known use, and a limit on one of its number fields. */
+export function checkRule(grant, action, rule) {
+    const info = grant.actions.find(one => one.name === action);
+    if (info === undefined)
+        return { ok: false, said: `${grant.tool} has no action called ${action}. Its actions: ${grant.actions.map(one => one.name).join(", ")}.` };
+    if (rule.use !== "free" && rule.use !== "ask" && rule.use !== "never")
+        return { ok: false, said: "Choose do it, ask first or never." };
+    // v97: the action that undoes this one, when a person presses Undo on its receipt.
+    const undo = typeof rule.undo === "string" && rule.undo !== "" ? rule.undo : null;
+    if (undo !== null && (undo === action || !grant.actions.some(one => one.name === undo)))
+        return { ok: false, said: `${grant.tool} has no other action called ${undo} to undo ${action} with.` };
+    const withUndo = (made) => ({ ok: true, rule: undo === null ? made : { ...made, undo } });
+    if (rule.use !== "free" || rule.limit === undefined || rule.limit === null)
+        return withUndo({ use: rule.use });
+    const field = String(rule.limit.field ?? "");
+    const over = numberOf(rule.limit.over);
+    if (field === "")
+        return { ok: false, said: `Choose which number of ${action} the limit is on.` };
+    if (info.input !== null && !numberFields(info).includes(field))
+        return { ok: false, said: `${action} has no number called ${field}.` };
+    if (over === null || over < 0 || over > 1e12)
+        return { ok: false, said: "A limit is a number, 0 or more." };
+    return withUndo({ use: "free", limit: { field, over } });
+}
+/** Set the rules for some of a granted tool's actions; the others keep theirs. */
+export function setToolRules(store, mate, tool, changes, by, now) {
+    const grant = store.teammateGrant(mate.id, tool);
+    if (grant === null)
+        return { ok: false, said: `It doesn't use ${tool}. Let it use ${tool} first.` };
+    const rules = { ...grant.rules };
+    for (const [action, change] of Object.entries(changes)) {
+        const checked = checkRule(grant, action, change);
+        if (!checked.ok)
+            return { ok: false, said: checked.said };
+        rules[action] = checked.rule;
+    }
+    store.saveTeammateGrant({ teammate: mate.id, tool, actions: grant.actions, rules }, by, now);
+    return { ok: true, said: "Saved. Its next turn uses these rules." };
+}
+const blank = (text) => redactSecretLines(text, scanForSecrets(text));
+/**
+ * Make one call now: a free one, or one a person approved (exactly as they
+ * saw it). What the tool said is kept on the receipt, secrets scrubbed; a
+ * tool that says it failed is an answer the teammate reads, not trouble.
+ */
+export async function makeCall(store, call, repo, io, now, options = {}) {
+    // Its rules are read again at the moment of the call: a tool taken away, or an action set to never, since it was approved stops it.
+    // (A person's own undo (v97) needs the tool still granted, not the teammate's rule for that action.)
+    const grant = store.teammateGrant(call.teammate, call.tool);
+    if (grant === null || (options.byPerson !== true && ruleFor(grant, call.action, call.input).use === "never")) {
+        store.moveTeammateCall(call.id, ["approved", "running"], { state: "refused", result: "Its rules changed before the call was made." }, now);
+        return store.teammateCall(call.id);
+    }
+    // Sprint 8: nor does a call to a tool the organisation policy doesn't allow (a person's undo included).
+    const disallowed = toolRefusal(store.orgPolicy(), call.tool);
+    if (disallowed !== null) {
+        store.moveTeammateCall(call.id, ["approved", "running"], { state: "refused", result: disallowed }, now);
+        return store.teammateCall(call.id);
+    }
+    if (call.state !== "running" && !store.moveTeammateCall(call.id, ["approved"], { state: "running" }, now))
+        return store.teammateCall(call.id);
+    const tool = projectToolsOf(store, repo).find(one => one.name === call.tool);
+    if (tool === undefined) {
+        store.moveTeammateCall(call.id, ["running"], { state: "failed", result: `There's no tool called ${call.tool} in this project any more.` }, now);
+        return store.teammateCall(call.id);
+    }
+    const values = readToolSecrets(repo, tool.name, io.toolHome);
+    let answer;
+    try {
+        answer = await (io.callTool ?? ((spec, secrets, name, given) => callProjectTool(spec, secrets, name, given, { timeoutMs: 120_000, omitEnv: ALL_CREDENTIAL_ENV })))(tool.spec, values, call.action, call.input);
+    }
+    catch (error) {
+        answer = { ok: false, problem: error instanceof Error ? error.message : "It couldn't be reached." };
+    }
+    const text = answer.ok ? blank(scrubSecrets(answer.text, values)).trim() : answer.problem;
+    const kept = text.length <= RESULT_CHARS ? text : `${text.slice(0, RESULT_CHARS - 1)}…`;
+    store.moveTeammateCall(call.id, ["running"], { state: answer.ok && !answer.isError ? "done" : "failed", result: kept || (answer.ok ? "(no answer)" : "It couldn't be reached.") }, now);
+    return store.teammateCall(call.id);
+}
+/** A receipt in words: what happened to the call. */
+export function callOutcome(call) {
+    switch (call.state) {
+        case "asked": return "waiting for approval";
+        case "approved": return `${call.decidedBy} approved it; making it`;
+        case "running": return "making it";
+        case "done": return call.decidedBy === null ? "done" : `${call.decidedBy} approved it; done`;
+        case "failed": return call.decidedBy === null ? "failed" : `${call.decidedBy} approved it; it failed`;
+        case "denied": return `${call.decidedBy ?? "A person"} denied it`;
+        default: return "not made";
+    }
+}
+/** A receipt as a person reads it on the card: what happened, and who decided. */
+export function receiptWords(store, call) {
+    switch (call.state) {
+        case "asked": {
+            const question = store.teammateQuestionForCall(call.id);
+            return `Waiting for ${question?.askedOf ?? "a person"} to approve`;
+        }
+        case "approved":
+        case "running": return call.decidedBy === null ? "Making it now" : `${call.decidedBy} approved · making it now`;
+        case "done": return call.undoneBy !== null ? `Done · undone by ${call.undoneBy}` : call.undoOf !== null ? `Undid ${store.teammateCall(call.undoOf)?.action ?? "a call"} · done` : call.decidedBy === null ? "Done" : `${call.decidedBy} approved · done`;
+        case "failed": return call.decidedBy === null ? "Failed" : `${call.decidedBy} approved · failed`;
+        case "denied": {
+            const said = store.teammateQuestionForCall(call.id)?.answer;
+            return `${call.decidedBy ?? "A person"} said no${said ? `: ${said}` : ""}`;
+        }
+        default: return `Not made: ${call.result ?? "outside its rules"}`;
+    }
+}
+/** The Tools section's form, read into rule changes: every action the grant knows. */
+export function rulesFromForm(grant, field) {
+    return Object.fromEntries(grant.actions.flatMap(action => {
+        const use = field(`use.${action.name}`);
+        if (use === null)
+            return [];
+        const undo = field(`undo.${action.name}`) ?? "";
+        return [[action.name, { ...(use === "limit" ? { use: "free", limit: { field: field(`field.${action.name}`) ?? "", over: field(`over.${action.name}`) ?? "" } } : { use }), undo }]];
+    }));
+}

package/dist/teammate-week.d.ts

@@ -0,0 +1,68 @@
+import type { Store, TeammateCallRow, TeammateRow } from "./store.js";
+import { type ToolIo } from "./teammate-tools.js";
+type Done = {
+    ok: true;
+    said: string;
+} | {
+    ok: false;
+    said: string;
+};
+export type Week = {
+    since: string;
+    turns: number;
+    failedTurns: number;
+    costUsd: number | null;
+    minutes: number;
+    decided: number;
+    handled: number;
+    handed: number;
+    asked: number;
+    calls: {
+        made: number;
+        approved: number;
+        denied: number;
+        refused: number;
+        undone: number;
+    };
+    overrides: {
+        said: string;
+        at: string;
+        href: string | null;
+    }[];
+    undoable: {
+        call: number;
+        words: string;
+        undo: string;
+        at: string;
+        href: string | null;
+    }[];
+};
+/** The undo action a call's rule names, when there is one and the call can still be undone. */
+export declare function undoFor(store: Store, call: TeammateCallRow): string | null;
+/** The last seven days (or since a time) for one teammate. */
+export declare function weekOf(store: Store, mate: TeammateRow, now: Date, since?: string): Week;
+/** The week in words its manager reads at a glance. */
+export declare function weekWords(mate: TeammateRow, week: Week): string;
+/** Each Monday from 9:00 (this computer's time), the week's report to each active teammate's manager, once; or now, for one. */
+export declare function sendTeammateWeeklies(store: Store, repo: string, now: Date, only?: number | null): number;
+/**
+ * A person asks to undo one of its tool calls with the action its manager
+ * named: the undo call is recorded at once (the same input, as them), and
+ * made by finishUndo — right away on the page, or by the worker's next pass
+ * when it was asked for in chat. Both calls keep their receipts.
+ */
+export declare function requestUndo(store: Store, mate: TeammateRow, id: number, by: string, now: Date): {
+    ok: true;
+    call: number;
+    said: string;
+} | {
+    ok: false;
+    said: string;
+};
+/** Make a requested undo call; if the tool says it failed, the original call stands (and can be undone again). */
+export declare function finishUndo(store: Store, id: number, io: ToolIo, now: Date): Promise<Done>;
+/** The worker's pass: undo calls asked for in chat, made now. */
+export declare function runRequestedUndos(store: Store, io: ToolIo, now: Date): Promise<number>;
+/** Undo, on the page: asked for and made at once. */
+export declare function undoCall(store: Store, mate: TeammateRow, id: number, by: string, io: ToolIo, now: Date): Promise<Done>;
+export {};

package/dist/teammate-week.js

@@ -0,0 +1,132 @@
+/**
+ * A teammate's week (v97): what it did, what it cost, what its people
+ * overrode, and its receipts — on its page, and each Monday morning to its
+ * manager in their chat app.
+ *
+ * Cost is what the Claude CLI reports for each turn (at API prices; a Claude
+ * plan covers subscription turns). Overrides are the calls its people turned
+ * down and the cards someone moved by hand right after it moved them.
+ *
+ * Undo, where the tool can: a manager names, per action, another action of
+ * the same tool that undoes it (remove_label for add_label, say). Undo makes
+ * that call with the same input, as the person who pressed it, and both calls
+ * keep their receipts.
+ */
+import { flowCardHref } from "./flow-engine.js";
+import { labelOf, nameOf } from "./teammate-admin.js";
+import { callWords, makeCall } from "./teammate-tools.js";
+const WEEK_MS = 7 * 86_400_000;
+const money = (usd) => usd < 0.01 ? "under 1¢" : usd < 10 ? `$${usd.toFixed(2)}` : `$${Math.round(usd)}`;
+/** The undo action a call's rule names, when there is one and the call can still be undone. */
+export function undoFor(store, call) {
+    if (call.state !== "done" || call.undoneBy !== null || call.undoOf !== null)
+        return null;
+    const grant = store.teammateGrant(call.teammate, call.tool);
+    const undo = grant?.rules[call.action]?.undo;
+    return undo !== undefined && grant.actions.some(one => one.name === undo) ? undo : null;
+}
+/** The last seven days (or since a time) for one teammate. */
+export function weekOf(store, mate, now, since = new Date(now.getTime() - WEEK_MS).toISOString()) {
+    const turns = store.teammateTurns(mate.id, since);
+    const costs = turns.map(one => one.costUsd).filter((one) => one !== null);
+    const events = store.teammateEvents(mate.id, 5000, since);
+    const count = (kind) => events.filter(one => one.kind === kind).length;
+    const calls = store.teammateCallsOf(mate.id, 5000, since).filter(one => one.undoOf === null);
+    const hrefOf = (card) => { const found = card === null ? null : store.getFlowCard(card); return found === null ? null : flowCardHref(found.flow, found.id); };
+    const name = nameOf(mate);
+    const denied = calls.filter(one => one.state === "denied").map(one => {
+        const words = store.teammateQuestionForCall(one.id)?.answer;
+        return { said: `${one.decidedBy ?? "Someone"} turned down ${callWords(one.tool, one.action, one.input, 160)}${words ? `: “${words.slice(0, 160)}”` : ""}`, at: one.decidedAt ?? one.createdAt, href: hrefOf(one.card) };
+    });
+    const moved = store.flowMovesOverridden(`${name} (AI)`, since).map(one => ({ said: `${one.by} moved “${one.title.slice(0, 80)}” after ${name} did`, at: one.at, href: flowCardHref(one.flow, one.card) }));
+    return {
+        since, turns: turns.length, failedTurns: turns.filter(one => !one.ok).length, costUsd: costs.length === 0 ? null : Math.round(costs.reduce((sum, one) => sum + one, 0) * 1e6) / 1e6,
+        minutes: Math.round(turns.reduce((sum, one) => sum + one.ms, 0) / 60_000),
+        decided: count("decided"), handled: count("handled"), handed: count("handed"), asked: count("asked"),
+        calls: { made: calls.filter(one => one.state === "done" || one.state === "failed").length, approved: calls.filter(one => one.decidedBy !== null && one.state !== "denied" && one.state !== "refused").length,
+            denied: calls.filter(one => one.state === "denied").length, refused: calls.filter(one => one.state === "refused").length, undone: calls.filter(one => one.undoneBy !== null).length },
+        overrides: [...denied, ...moved].sort((a, b) => b.at.localeCompare(a.at)).slice(0, 20),
+        undoable: calls.flatMap(one => { const undo = undoFor(store, one); return undo === null ? [] : [{ call: one.id, words: callWords(one.tool, one.action, one.input, 200), undo, at: one.createdAt, href: hrefOf(one.card) }]; }).reverse().slice(0, 20),
+    };
+}
+/** The week in words its manager reads at a glance. */
+export function weekWords(mate, week) {
+    const name = nameOf(mate);
+    const quiet = week.turns === 0 && week.decided + week.handled + week.handed + week.asked + week.calls.made === 0;
+    if (quiet)
+        return `${name} had nothing to do this week.`;
+    const lines = [
+        `${name} decided ${week.decided}, handled ${week.handled}, handed ${week.handed} to people and asked ${week.asked} question${week.asked === 1 ? "" : "s"}.`,
+        `Tool calls: ${week.calls.made} made${week.calls.approved > 0 ? ` (${week.calls.approved} after a person approved)` : ""}${week.calls.denied > 0 ? `, ${week.calls.denied} turned down` : ""}${week.calls.refused > 0 ? `, ${week.calls.refused} outside its rules` : ""}${week.calls.undone > 0 ? `, ${week.calls.undone} undone` : ""}.`,
+        `${week.turns} turn${week.turns === 1 ? "" : "s"}${week.failedTurns > 0 ? ` (${week.failedTurns} failed)` : ""}, about ${week.minutes} minute${week.minutes === 1 ? "" : "s"} of thinking${week.costUsd === null ? "" : `, ${money(week.costUsd)} at API prices`}.`,
+        ...(week.overrides.length === 0 ? ["Nobody overrode it."] : [`You overrode it ${week.overrides.length} time${week.overrides.length === 1 ? "" : "s"}:`, ...week.overrides.slice(0, 5).map(one => `• ${one.said}`)]),
+    ];
+    return lines.join("\n");
+}
+/** Each Monday from 9:00 (this computer's time), the week's report to each active teammate's manager, once; or now, for one. */
+export function sendTeammateWeeklies(store, repo, now, only = null) {
+    const monday = new Date(now);
+    monday.setHours(9, 0, 0, 0);
+    monday.setDate(monday.getDate() - ((monday.getDay() + 6) % 7));
+    let sent = 0;
+    for (const mate of store.teammates([repo])) {
+        // One a week, from Monday 9:00; a teammate that joined since then has its first next Monday.
+        if (only !== null ? mate.id !== only : mate.state !== "active" || now < monday || (mate.weeklyAt ?? mate.createdAt) >= monday.toISOString())
+            continue;
+        store.updateTeammate(mate.id, { weeklyAt: now.toISOString() }, "weekly", now);
+        const week = weekOf(store, mate, now);
+        if (week.turns === 0 && only === null)
+            continue;
+        store.enqueueNotification({ dedupeKey: `teammate-weekly:${mate.id}:${now.toISOString().slice(0, only === null ? 10 : 19)}`, kind: "teammate-weekly", recipient: mate.manager,
+            subject: `${labelOf(mate)}: the week`, body: weekWords(mate, week), link: `/teammates/${mate.id}#week`, source: { project: repo } }, now);
+        sent++;
+    }
+    return sent;
+}
+/**
+ * A person asks to undo one of its tool calls with the action its manager
+ * named: the undo call is recorded at once (the same input, as them), and
+ * made by finishUndo — right away on the page, or by the worker's next pass
+ * when it was asked for in chat. Both calls keep their receipts.
+ */
+export function requestUndo(store, mate, id, by, now) {
+    const call = store.teammateCall(id);
+    if (call === null || call.teammate !== mate.id)
+        return { ok: false, said: "No such call." };
+    const undo = undoFor(store, call);
+    if (undo === null)
+        return { ok: false, said: call.undoneBy !== null ? `${call.undoneBy} already undid it.` : "That call can't be undone here." };
+    return store.transact(() => {
+        if (!store.markTeammateCallUndone(call.id, by, now))
+            return { ok: false, said: "Someone undid it just now." };
+        const made = store.addTeammateCall({ teammate: mate.id, card: call.card, entry: call.entry, tool: call.tool, action: undo, input: call.input, rule: "free",
+            why: `${by} undid ${call.action} (call ${call.id}).`, state: "approved", undoOf: call.id, decidedBy: by }, now);
+        return { ok: true, call: made, said: `Undoing it with ${undo}.` };
+    });
+}
+/** Make a requested undo call; if the tool says it failed, the original call stands (and can be undone again). */
+export async function finishUndo(store, id, io, now) {
+    const pending = store.teammateCall(id);
+    const mate = pending === null ? null : store.getTeammate(pending.teammate);
+    if (pending === null || mate === null || pending.undoOf === null || pending.state !== "approved")
+        return { ok: false, said: "That undo was already made." };
+    const made = await makeCall(store, pending, mate.repo, io, now, { byPerson: true });
+    if (made.state === "done")
+        return { ok: true, said: `Undone: ${callWords(made.tool, made.action, made.input, 120)}. ${made.result ?? ""}`.trim() };
+    store.clearTeammateCallUndone(pending.undoOf, now);
+    return { ok: false, said: `The undo call failed: ${made.result ?? "no answer"}. The original call stands.` };
+}
+/** The worker's pass: undo calls asked for in chat, made now. */
+export async function runRequestedUndos(store, io, now) {
+    let made = 0;
+    for (const call of store.pendingTeammateUndos()) {
+        await finishUndo(store, call.id, io, now);
+        made++;
+    }
+    return made;
+}
+/** Undo, on the page: asked for and made at once. */
+export async function undoCall(store, mate, id, by, io, now) {
+    const asked = requestUndo(store, mate, id, by, now);
+    return asked.ok ? finishUndo(store, asked.call, io, now) : asked;
+}

package/dist/teammate-work.d.ts

@@ -0,0 +1,76 @@
+/**
+ * A teammate's turn on a card (v92), run by the flow step pass.
+ *
+ * The turn reads the zone, the card (as data) and what its people told it,
+ * and answers with one decision (teammates.ts). This carries the decision
+ * out within the zone's own choices, and writes it down — what it did and
+ * why — in the card's history and the teammate's log:
+ *
+ * - "Person decides" zone: approve (the draft as written, or as it rewrote
+ *   it), send back with a note, or hand it to the zone's person, whose
+ *   decision then arrives in their chat app as always.
+ * - "Teammate handles it" zone: pick one of the zone's answers (its text is
+ *   kept for the next zones), ask its person a question and wait for the
+ *   answer, or say it can't and take the failure path.
+ *
+ * Either way (v94), before it decides it may use the project tools its
+ * manager let it use: each call is checked against its rule for that action
+ * (teammate-tools.ts), made at once or put to its person first, and kept as
+ * a receipt; the turn goes on with what the tool answered.
+ */
+import type { FlowCardRow, FlowRow, Store, TeammateRow } from "./store.js";
+import type { FlowDefinition, FlowStage } from "./flows.js";
+import { type TurnRunner } from "./teammates.js";
+import { type ToolIo } from "./teammate-tools.js";
+/** A question waits for its answer this long before the step is due again on its own: never, in practice. */
+export declare const ASKED = "9999-12-31T00:00:00.000Z";
+/** v94: tool calls one visit of a card may make, and turns one step run may take, before it must decide with what it has. */
+export declare const CALLS_PER_VISIT = 12;
+/** The two answers an ask-first call offers; words instead tell the teammate what to do. */
+export declare const APPROVE = "approve", DENY = "deny";
+export type TeammateOutcome = {
+    state: "passed" | "failed" | "retry" | "waiting";
+    said: string;
+    log?: string;
+    decisionJson?: string;
+    nextAt?: string;
+};
+/** The Claude model a teammate's turns run on: its own, or the lead chat's Claude model, or Claude's default. */
+export declare function teammateModel(store: Store, mate: TeammateRow): string;
+/** Whether a teammate can take a turn now: active, readable, and under its daily limit. */
+export declare function teammateReady(store: Store, mate: TeammateRow | null, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
+/** The answers a "Teammate handles it" zone offers, each with the zone it leads to. */
+export declare function handleAnswers(stage: FlowStage): {
+    answer: string;
+    to: string | null;
+}[];
+/**
+ * Run one teammate turn on a card and carry out what it decided. With tools
+ * (v94) a turn is a short loop: each tool call it asks for is made (or put to
+ * its person, and the turn waits), and it decides again with the answer —
+ * until it decides, or it has used its tools as much as a visit allows.
+ */
+export declare function teammateTurn(store: Store, flow: FlowRow, definition: FlowDefinition, stage: FlowStage, card: FlowCardRow, mate: TeammateRow, now: Date, io: {
+    turn?: TurnRunner;
+    evidenceRoot?: string;
+} & ToolIo): Promise<TeammateOutcome>;
+/** A person answers a teammate's question: once, by the person it was asked of; the card's turn is due again. */
+export declare function answerTeammateQuestion(store: Store, id: number, answer: {
+    choice: string | null;
+    text: string | null;
+    by: string;
+    via: string;
+}, now: Date): {
+    ok: true;
+    said: string;
+} | {
+    ok: false;
+    said: string;
+};
+/** A card's link, for messages about it. */
+export declare const teammateCardHref: (flow: number, card: number) => string;