toolroll 0.5.0

package/dist/coordinator-proposals.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Proposals over the MCP gateway (mate arc v3, §9). A coordinator may
+ * propose what the mate may propose — next, reserve, hold, unhold, scope,
+ * cancel, answer — and a row is all it writes: any approver whose ceiling
+ * admits the repo confirms it through `confirmCoordinatorProposal`. The
+ * token re-authenticates INSIDE the transaction (the session's `who` is a
+ * courtesy, exactly as for filing); the proposal counts against the
+ * credential's hourly filing rate and a per-credential pending cap; the
+ * payload carries the same CAS material the mate's does, so a stale row
+ * refuses at the door in the same words.
+ */
+import type { CoordinatorProposalKind, Store } from "./store.js";
+export declare const PER_CID_PENDING_PROPOSALS = 20;
+export type ProposeOutcome = {
+    ok: true;
+    id: number;
+    kind: CoordinatorProposalKind;
+    awaiting: string;
+} | {
+    ok: false;
+    reason: "unauthenticated" | "revoked" | "rate-limited" | "pending-cap" | "not-found" | "bad-args" | "not-proposable";
+    message: string;
+};
+/** The coordinator's proposal as a row; the shape of `args` is the MCP tool's. */
+export declare function proposeAsCoordinator(store: Store, token: string, kind: CoordinatorProposalKind, args: Record<string, unknown>, now: Date, 
+/** The decisions this connection has read with get_decision — an answer needs one (v3 review, finding 6). */
+seen?: {
+    readDecisions: ReadonlySet<number>;
+}): ProposeOutcome;

package/dist/coordinator-proposals.js

@@ -0,0 +1,137 @@
+import { validateScopeText } from "./task-text.js";
+import { authenticateCoordinator } from "./coordinator.js";
+import { decisionOver, honestText, readTouches, readAcceptanceArg } from "./mate-tools.js";
+export const PER_CID_PENDING_PROPOSALS = 20;
+const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** The coordinator's proposal as a row; the shape of `args` is the MCP tool's. */
+export function proposeAsCoordinator(store, token, kind, args, now, 
+/** The decisions this connection has read with get_decision — an answer needs one (v3 review, finding 6). */
+seen = { readDecisions: new Set() }) {
+    return store.transact(() => {
+        store.sweepCoordinatorProposals(now);
+        const auth = authenticateCoordinator(store, token);
+        if (!auth.ok) {
+            return auth.reason === "revoked" || auth.reason === "expired"
+                ? { ok: false, reason: "revoked", message: auth.reason === "expired" ? "this credential expired — ask the operator for a new one" : "this credential was revoked — ask the operator for a new one" }
+                : { ok: false, reason: "unauthenticated", message: "no live coordinator credential matches this token" };
+        }
+        const { who } = auth;
+        // Filings and proposals share the hourly window: both are asks of the
+        // operator's attention.
+        const windowStart = new Date(now.getTime() - 3_600_000);
+        const filed = Number(store.handle.prepare("SELECT COUNT(*) AS n FROM coordinator_event WHERE cid = ? AND kind = 'filed' AND created_at > ?").get(who.cid, windowStart.toISOString())?.["n"] ?? 0);
+        const proposed = store.coordinatorProposalsSince(who.cid, windowStart);
+        if (filed + proposed >= who.perHour) {
+            return { ok: false, reason: "rate-limited", message: `rate-limited: ${filed + proposed} filed or proposed in the last hour — try later` };
+        }
+        const pending = store.listCoordinatorProposals({ repos: null, cid: who.cid, states: ["pending"], limit: PER_CID_PENDING_PROPOSALS + 1 }).length;
+        if (pending >= PER_CID_PENDING_PROPOSALS) {
+            return { ok: false, reason: "pending-cap", message: `${pending} of your proposals are still waiting on the operator — they resolve before more file` };
+        }
+        const built = buildPayload(store, who, kind, args, now, seen);
+        if (!built.ok)
+            return built;
+        const id = store.fileCoordinatorProposalRow({ cid: who.cid, name: who.name, repo: built.repo, kind, payload: built.payload }, now);
+        return { ok: true, id, kind, awaiting: built.awaiting };
+    });
+}
+function admittedTask(store, who, args) {
+    const raw = args["ref"];
+    if (typeof raw !== "string" || !TASK_ID.test(raw))
+        return null;
+    const ref = store.lookupRef(raw);
+    if (ref === null || ref.repo === null || !who.repos.includes(ref.repo))
+        return null;
+    return { taskId: raw, refId: ref.id, repo: ref.repo };
+}
+function buildPayload(store, who, kind, args, now, seen) {
+    const notFound = () => ({ ok: false, reason: "not-found", message: "not-found: no such task in your repositories" });
+    const bad = (message) => ({ ok: false, reason: "bad-args", message });
+    const confirmation = "the operator's confirmation";
+    if (kind === "answer") {
+        const decisionId = args["decision"];
+        if (typeof decisionId !== "number" || !Number.isInteger(decisionId) || decisionId < 1)
+            return bad("decision is its id");
+        const found = decisionOver(store, who.repos, decisionId, now);
+        if (found === null)
+            return { ok: false, reason: "not-found", message: "not-found: no such decision in your repositories" };
+        if (found["state"] !== "open")
+            return { ok: false, reason: "not-proposable", message: "that decision is no longer open" };
+        if (!seen.readDecisions.has(decisionId))
+            return { ok: false, reason: "not-proposable", message: "read the decision first with get_decision — an answer chosen without its consequences is a guess" };
+        const options = found["options"];
+        const chosen = options.find(one => one.id === args["option"]);
+        if (chosen === undefined)
+            return bad(`option must be one of ${options.map(one => one.id).join(", ")}`);
+        if (!honestText(args["rationale"], 400))
+            return bad("rationale is plain text ≤400");
+        const repo = who.repos[found["repoIndex"]];
+        return {
+            ok: true,
+            repo,
+            payload: { decision: decisionId, task: found["task"], option: chosen.id, optionLabel: chosen.label, reversible: chosen.reversible, rationale: args["rationale"], readConsequences: true },
+            awaiting: chosen.reversible ? confirmation : "the operator's explicit confirmation — this option is irreversible",
+        };
+    }
+    const task = admittedTask(store, who, args);
+    if (task === null)
+        return notFound();
+    if (kind === "next") {
+        const position = store.queuePosition(task.taskId);
+        if (position === null)
+            return { ok: false, reason: "not-proposable", message: "that task is not queued" };
+        if (position.position === 1)
+            return { ok: false, reason: "not-proposable", message: "that task is already at the front of its column" };
+        return { ok: true, repo: task.repo, payload: { task: task.taskId, queueRevision: store.queueRevision(), position: position.position, of: position.total, column: position.column }, awaiting: confirmation };
+    }
+    if (kind === "reserve") {
+        const worker = args["worker"];
+        if (worker !== null && (typeof worker !== "string" || !store.listRunners().some(one => one.name === worker && one.retiredAt === null))) {
+            return bad("worker must be a registered, active worker name, or null for the shared queue");
+        }
+        const position = store.queuePosition(task.taskId);
+        if (position === null)
+            return { ok: false, reason: "not-proposable", message: "that task is not queued" };
+        if ((position.column ?? null) === worker)
+            return { ok: false, reason: "not-proposable", message: "that task is already in that column" };
+        return { ok: true, repo: task.repo, payload: { task: task.taskId, worker, queueRevision: store.queueRevision(), position: position.position, column: position.column }, awaiting: confirmation };
+    }
+    if (kind === "hold") {
+        if (!honestText(args["reason"], 200))
+            return bad("reason is plain text ≤200");
+        const existing = store.activeHolds(task.refId, now).find(one => one.ownerKind === "operator");
+        return { ok: true, repo: task.repo, payload: { task: task.taskId, reason: args["reason"], sawHold: existing?.id ?? null }, awaiting: confirmation };
+    }
+    if (kind === "unhold") {
+        const hold = store.activeHolds(task.refId, now).find(one => one.ownerKind === "operator");
+        if (hold === undefined)
+            return { ok: false, reason: "not-proposable", message: "the operator holds no hold on that task" };
+        return { ok: true, repo: task.repo, payload: { task: task.taskId, holdId: hold.id }, awaiting: confirmation };
+    }
+    if (kind === "scope") {
+        if (typeof args["goal"] !== "string" || (args["not"] != null && typeof args["not"] !== "string"))
+            return bad("Goal and exclusions must be text.");
+        const badText = validateScopeText({ goal: args["goal"], outOfScope: args["not"] ?? null });
+        if (badText !== null)
+            return bad(badText.message);
+        const not = args["not"] ?? null;
+        if (!honestText(args["goal"], 2_000) || (not !== null && not.trim() !== "" && !honestText(not, 2_000)))
+            return bad("Task text cannot contain credentials.");
+        const touches = readTouches(args["touches"]);
+        if (touches === null)
+            return bad("touches is up to 50 plain paths");
+        const acceptance = readAcceptanceArg(args["acceptance"]);
+        if (acceptance === null)
+            return bad("acceptance is required: at least one criterion with an id, statement, and evidence kinds");
+        if (store.hasLiveClaim(task.refId, now))
+            return { ok: false, reason: "not-proposable", message: "a worker is building that task right now — its scope cannot change under it" };
+        const scope = store.getScope(task.taskId);
+        return { ok: true, repo: task.repo, payload: { task: task.taskId, goal: args["goal"], not, touches, acceptance, sawDigest: scope?.digest ?? null }, awaiting: "the operator's confirmation, then a password to approve" };
+    }
+    if (kind === "cancel") {
+        if (!honestText(args["reason"], 200))
+            return bad("reason is plain text ≤200");
+        return { ok: true, repo: task.repo, payload: { task: task.taskId, reason: args["reason"] }, awaiting: "the operator arming the cancel on the task" };
+    }
+    return bad("unknown proposal kind");
+}

package/dist/coordinator.d.ts

@@ -0,0 +1,186 @@
+/**
+ * The coordinator principal (MCP gateway spec v6; DESIGN.md §9b).
+ *
+ * A coordinator is the ONE credential the MCP surface accepts: minted by
+ * an operator password ceremony, hashed at rest, repo-scoped at the mint,
+ * rate-limited, revocable — and able to do exactly one thing: file a
+ * proposal through the canonical door. What it files is an ordinary
+ * UNAPPROVED task; admission is the operator's existing scope ceremony,
+ * and the quarantine (sealScopeApproval's mode-kind refusal + the claim
+ * primitive's exclusion) keeps every pre-seal road shut.
+ *
+ * The brand: `VerifiedCoordinator` is disjoint from the operator's
+ * `VerifiedAuthor` by construction, and its maker is module-private —
+ * the exported-cast mistake is named in the spec and not repeated here.
+ * Steering and every operator-speech surface cannot accept this type.
+ */
+import type { Store } from "./store.js";
+import { type WorkSummary } from "./work-summary.js";
+import { assignmentBrief } from "./assignment.js";
+declare const verifiedCoordinatorBrand: unique symbol;
+export type VerifiedCoordinator = {
+    readonly [verifiedCoordinatorBrand]: true;
+    readonly cid: string;
+    readonly name: string;
+    readonly repos: readonly string[];
+    readonly perHour: number;
+};
+export type MintResult = {
+    ok: true;
+    cid: string;
+    token: string;
+    repos: string[];
+} | {
+    ok: false;
+    reason: "bad-name" | "name-taken" | "bad-rate" | "no-repos";
+};
+export declare function mintCoordinator(store: Store, input: {
+    name: string;
+    repos: readonly string[];
+    perHour?: number;
+    by: string;
+    now: Date;
+    /** v101: how long it lives (90 days unless said; at most a year). */
+    days?: number;
+    /** Injected in tests. */
+    newToken?: () => string;
+    newCid?: () => string;
+}): MintResult;
+export type CoordinatorAuth = {
+    ok: true;
+    who: VerifiedCoordinator;
+} | {
+    ok: false;
+    reason: "unknown" | "revoked" | "expired";
+};
+/** The token IS the identity — no name travels with it. Verified against
+ * the stored hash; the caller re-runs this INSIDE any mutating
+ * transaction (the startup check is a courtesy; the txn check is law). */
+export declare function authenticateCoordinator(store: Store, token: string): CoordinatorAuth;
+export declare function revokeCoordinator(store: Store, cid: string, by: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "unknown" | "already-revoked";
+};
+export type CoordinatorRow = {
+    cid: string;
+    name: string;
+    repos: string[];
+    perHour: number;
+    createdBy: string;
+    createdAt: string;
+    revokedAt: string | null;
+    lastFiledAt: string | null;
+    /** v101: when it stops (null: made before expiry existed, until renewed). */
+    expiresAt: string | null;
+};
+export declare function listCoordinators(store: Store): CoordinatorRow[];
+export declare const PER_CID_OUTSTANDING = 10;
+export declare const GLOBAL_OUTSTANDING = 50;
+export type FileOutcome = {
+    ok: true;
+    id: string;
+    replayed: boolean;
+} | {
+    ok: false;
+    reason: "unauthenticated" | "revoked" | "bad-key" | "idempotency-conflict" | "rate-limited" | "outstanding-cap" | "global-cap" | string;
+    message: string;
+};
+/**
+ * The one write the MCP surface owns, as ONE transaction: authenticate →
+ * revocation re-check → replay lookup → rate window → caps → the
+ * canonical door → the cid stamp → idempotency + event rows. The rate
+ * window reads the event ledger (filings are events, so the window and
+ * the audit cannot disagree), and a replay charges no slot.
+ */
+export declare function fileCoordinatorProposal(store: Store, token: string, input: {
+    repo: string;
+    title: string;
+    intent?: string;
+    idempotencyKey: string;
+    deliverable?: "branch" | "report";
+}, now: Date): FileOutcome;
+export declare function statusFor(store: Store, who: VerifiedCoordinator, now: Date): {
+    waitsOnYou: number;
+    waits: {
+        approvals: number;
+        questions: number;
+        incidents: number;
+        picks: number;
+    };
+    running: number;
+    builtToday: number;
+    failedToday: number;
+    repos: {
+        repo: string;
+        queued: number;
+        running: number;
+    }[];
+};
+export declare function listTasksFor(store: Store, who: VerifiedCoordinator, filter: {
+    state?: string;
+    repo?: string;
+    cursor?: number;
+    limit?: number;
+}, now: Date): {
+    tasks: {
+        ref: string;
+        title: string;
+        state: string;
+        chip: string;
+        repo: string;
+        filedVia: string | null;
+    }[];
+    nextCursor: number | null;
+};
+export declare function taskDetailFor(store: Store, who: VerifiedCoordinator, taskId: string, evidenceRoot?: string, now?: Date): {
+    ref: string;
+    title: string;
+    state: string;
+    repo: string;
+    work: WorkSummary | null;
+    assignment: ReturnType<typeof assignmentBrief>;
+    deliverable: "branch" | "report";
+    /** A finished scout's report (mate arc §10); null when there is none. */
+    report: {
+        title: string;
+        summary: string;
+        followUps: {
+            title: string;
+            goal: string;
+        }[];
+    } | {
+        problem: string;
+    } | null;
+    filedBy: string | null;
+    scope: {
+        sealed: boolean;
+        goal: string | null;
+        words: string[];
+    };
+    waits: string[];
+    attempts: {
+        outcome: string | null;
+        provider: string;
+        model: string | null;
+        startedAt: string;
+        finishedAt: string | null;
+        durationMs: number | null;
+        costMicrousd: number | null;
+    }[];
+    cost: {
+        totalMicrousd: number;
+        measuredRuns: number;
+        totalRuns: number;
+    };
+    evidence: {
+        id: number;
+        kind: string;
+        bytes: number;
+        sha256: string;
+        captureStatus: string | null;
+        mediaType: string;
+    }[];
+} | null;
+export {};