specpi 0.11.2 → 0.12.0

package/extensions/delegation/presentation.mjs

@@ -0,0 +1,315 @@
+import { stripVTControlCharacters } from "node:util";
+
+// Worker text is untrusted terminal content. Never interpret its ANSI, links or controls.
+const plain = (value) =>
+    stripVTControlCharacters(String(value ?? "").slice(0, 16000))
+        .replace(/[\p{Cc}\p{Cf}]/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim();
+const duration = (ms) => {
+    const seconds = Math.floor(Math.max(0, ms) / 1000);
+
+    return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+};
+
+const stateLabel = (job) => {
+    if (job.settling && !["running", "queued"].includes(job.state)) {
+        return ["complete", "partial", "needs_context"].includes(job.state) ? "finishing" : "stopping";
+    }
+
+    return (
+        { complete: "ready for review", partial: "partial · needs review", needs_context: "needs context" }[
+            job.state
+        ] ?? plain(job.state)
+    );
+};
+
+const stateColor = (job) => {
+    if (job.settling || job.state === "running") {
+        return "accent";
+    }
+
+    return job.state === "complete" ? "success" : "warning";
+};
+
+export function panelLines(view, width, theme, truncateToWidth) {
+    const fit = (text) => truncateToWidth(text, Math.max(1, width), "…");
+    const lines = [
+        fit(
+            theme.fg("accent", "Delegation") +
+                theme.fg(
+                    "muted",
+                    ` · ${view.active}/${view.concurrency} workers · ${view.calls}/${view.callLimit} calls`,
+                ),
+        ),
+    ];
+    for (const job of view.jobs) {
+        const state = width < 72 && job.state === "complete" && !job.settling ? "ready" : stateLabel(job);
+        const label = theme.fg(stateColor(job), state);
+        const identity = `${plain(job.id)} · ${plain(job.mode)}`;
+        const metrics = `${duration(job.elapsedMs)} · ${job.calls} model · ${job.tools} tools`;
+        if (width < 72) {
+            const name = truncateToWidth(identity, Math.max(1, width - state.length - 5), "…");
+            lines.push(fit(`  ${name} · ${label}`), fit(theme.fg("dim", `    ${metrics}`)));
+        } else {
+            const name = truncateToWidth(identity, Math.max(1, width - state.length - metrics.length - 8), "…");
+            lines.push(fit(`  ${name} · ${label}` + theme.fg("dim", ` · ${metrics}`)));
+        }
+    }
+
+    return lines;
+}
+
+/** One mounted component and one 1 Hz timer, only in a live TUI with occupied slots. */
+export function createLivePanel(getView, { truncateToWidth }) {
+    const key = "specpi-delegation-workers";
+    let context;
+    let timer;
+    let tui;
+    let mounted = false;
+    let view;
+    const dispose = () => {
+        clearTimeout(timer);
+        timer = undefined;
+        if (mounted) {
+            try {
+                context?.ui?.setWidget?.(key, undefined);
+            } catch {
+                // A closing terminal cannot interrupt session teardown.
+            }
+        }
+
+        mounted = false;
+        tui = undefined;
+        context = undefined;
+        view = undefined;
+    };
+
+    const update = () => {
+        clearTimeout(timer);
+        timer = undefined;
+        if (context?.mode !== "tui" || !context?.ui?.setWidget) {
+            return;
+        }
+
+        view = getView();
+        if (!view.jobs.length) {
+            if (mounted) {
+                context.ui.setWidget(key, undefined);
+                mounted = false;
+                tui = undefined;
+            }
+
+            return;
+        }
+
+        if (!mounted) {
+            mounted = true;
+            context.ui.setWidget(key, (activeTui, theme) => {
+                tui = activeTui;
+
+                return {
+                    invalidate() {},
+                    render: (width) => (view ? panelLines(view, width, theme, truncateToWidth) : []),
+                };
+            });
+        } else {
+            tui?.requestRender();
+        }
+
+        if (view.active > 0) {
+            timer = setTimeout(() => {
+                try {
+                    update();
+                } catch {
+                    // UI failure cannot escape an async timer or affect worker ownership.
+                }
+            }, 1000);
+            timer.unref?.();
+        }
+    };
+
+    return {
+        update,
+        dispose,
+        bind(ctx) {
+            dispose();
+            context = ctx;
+        },
+    };
+}
+
+export function readableStatus(state) {
+    const mode = state.enabled ? "enabled" : state.updating ? "updating model" : state.requested ? "paused" : "off";
+    const lines = [
+        `Delegation ${mode} · ${state.active}/${state.limits.concurrency} workers active`,
+        `Process budget: ${state.sessionCalls}/${state.limits.sessionCalls} model calls · ${state.sessionBatches}/${state.limits.sessionBatches} batches used`,
+        `Command Guard: ${plain(state.guard)}`,
+    ];
+    if (state.model) {
+        lines.push(
+            `Model: ${plain(state.model.provider)}/${plain(state.model.id)} · thinking ${plain(state.model.thinkingLevel ?? "configured")}`,
+        );
+    }
+
+    if (state.pauseReason) {
+        lines.push(plain(state.pauseReason));
+    }
+
+    for (const batch of state.batches.filter((item) => !item.retired)) {
+        lines.push(`Batch ${plain(batch.batchId)}`);
+        for (const job of batch.jobs) {
+            lines.push(
+                `  ${plain(job.jobId)} · ${job.disposition ? plain(job.disposition) : stateLabel(job)} · ${job.calls} model calls`,
+            );
+        }
+    }
+
+    return lines.join("\n");
+}
+
+export function readableLimits(state) {
+    const limits = Object.entries(state.limits).map(([name, value]) => {
+        const unit = name.endsWith("Bytes") ? " bytes" : name.endsWith("Ms") ? " ms" : "";
+        const label = name.replace(/(Bytes|Ms)$/u, "").replace(/[A-Z]/gu, (letter) => ` ${letter.toLowerCase()}`);
+
+        return `  ${label}: ${value}${unit}`;
+    });
+
+    return `${readableStatus(state)}\nFixed limits:\n${limits.join("\n")}\nBudgets do not reset on off/on or reload. Cancellation is best effort; no billing cap.`;
+}
+
+export function createToolRenderers({ truncateToWidth, wrapTextWithAnsi }) {
+    const component = (getLines) => {
+        let cachedWidth;
+        let cachedLines;
+
+        return {
+            invalidate() {
+                cachedWidth = undefined;
+            },
+            render(width) {
+                if (width === cachedWidth) {
+                    return cachedLines;
+                }
+
+                const lines = getLines().flatMap((line) => wrapTextWithAnsi(line, Math.max(1, width)));
+                const selected =
+                    lines.length > 120 ? [...lines.slice(0, 119), "… more in the structured tool response"] : lines;
+
+                cachedWidth = width;
+                cachedLines = selected.map((line) => truncateToWidth(line, Math.max(1, width), "…"));
+
+                return cachedLines;
+            },
+        };
+    };
+
+    const references = (items) =>
+        (items ?? []).map((item) => `${plain(item.sourceId)}:${item.lineStart}–${item.lineEnd}`).join(", ");
+
+    return {
+        renderCall(args, theme) {
+            return component(() => {
+                const operation = plain(args?.operation || "preparing");
+                const jobs = Array.isArray(args?.packet?.jobs)
+                    ? args.packet.jobs
+                          .slice(0, 2)
+                          .map((job) => `${plain(job.id)} (${plain(job.mode)})`)
+                          .join(", ")
+                    : plain(args?.jobId);
+
+                return [
+                    theme.fg("toolTitle", `Delegate · ${operation}`) + (jobs ? theme.fg("muted", ` · ${jobs}`) : ""),
+                ];
+            });
+        },
+        renderResult(result, { expanded, isPartial }, theme) {
+            return component(() => {
+                if (isPartial) {
+                    return [theme.fg("muted", "Waiting for worker results…")];
+                }
+
+                if (result.isError || result.details?.error) {
+                    return [
+                        theme.fg(
+                            "error",
+                            plain(result.content?.find((item) => item.type === "text")?.text ?? "Delegation failed"),
+                        ),
+                    ];
+                }
+
+                const data = result.details ?? {};
+                if (typeof data.enabled === "boolean") {
+                    return readableStatus(data)
+                        .split("\n")
+                        .map((line) => theme.fg("muted", line));
+                }
+
+                if (data.disposition) {
+                    return [
+                        theme.fg(
+                            "muted",
+                            `${plain(data.jobId)} · ${plain(data.disposition.decision)} · parent assessment`,
+                        ),
+                    ];
+                }
+
+                const lines = (data.jobs ?? []).map(
+                    (job) =>
+                        `${plain(job.jobId)} · ${job.disposition ? plain(job.disposition) : stateLabel(job)} · ${job.calls} model calls`,
+                );
+                for (const item of data.results ?? []) {
+                    if (!item.result) {
+                        if (item.error) {
+                            lines.push(theme.fg("warning", `${plain(item.receipt?.jobId)}: ${plain(item.error)}`));
+                        }
+
+                        continue;
+                    }
+
+                    const report = item.result;
+                    lines.push(
+                        theme.fg(
+                            "accent",
+                            `${plain(item.receipt?.jobId)} · ${report.findings.length} findings · advisory`,
+                        ),
+                    );
+                    if (expanded) {
+                        lines.push(plain(report.answer));
+                        for (const finding of report.findings) {
+                            lines.push(`${plain(finding.id)} [${plain(finding.confidence)}] ${plain(finding.claim)}`);
+                            lines.push(theme.fg("dim", `  Evidence: ${references(finding.evidence) || "none"}`));
+                            if (finding.contraryEvidence?.length) {
+                                lines.push(theme.fg("dim", `  Contrary: ${references(finding.contraryEvidence)}`));
+                            }
+                        }
+
+                        for (const requirement of report.requirements) {
+                            lines.push(
+                                theme.fg(
+                                    "dim",
+                                    `${plain(requirement.id)} · ${plain(requirement.status)} · ${references(requirement.evidence) || "no references"}`,
+                                ),
+                            );
+                        }
+
+                        for (const missing of report.missing) {
+                            lines.push(theme.fg("warning", `Missing: ${plain(missing)}`));
+                        }
+
+                        if (report.nextStep) {
+                            lines.push(`Next: ${plain(report.nextStep)}`);
+                        }
+                    }
+                }
+
+                if (!expanded && data.results?.some((item) => item.result)) {
+                    lines.push(theme.fg("dim", "Expand tool output for findings and evidence."));
+                }
+
+                return lines.length ? lines : [theme.fg("muted", "No new worker results.")];
+            });
+        },
+    };
+}

package/extensions/delegation/protocol.mjs

@@ -0,0 +1,296 @@
+import { DelegationError } from "./errors.mjs";
+import { createHash } from "node:crypto";
+
+export const LIMITS = Object.freeze({
+    concurrency: 2,
+    sessionBatches: 4,
+    sessionCalls: 32,
+    batchJobs: 2,
+    batchCalls: 8,
+    jobCalls: 4,
+    jobMs: 120_000,
+    batchMs: 300_000,
+    contextBytes: 256 * 1024,
+    retainedResponseBytes: 256 * 1024,
+    toolBytes: 64 * 1024,
+    toolCalls: 12,
+    resultBytes: 16 * 1024,
+    outputTokens: 8192,
+});
+
+export function bytes(value) {
+    return Buffer.byteLength(typeof value === "string" ? value : JSON.stringify(value), "utf8");
+}
+
+export function digest(value) {
+    const canonical = (item) => {
+        if (Array.isArray(item)) {
+            return item.map(canonical);
+        }
+
+        if (item && typeof item === "object") {
+            return Object.fromEntries(
+                Object.keys(item)
+                    .sort()
+                    .map((key) => [key, canonical(item[key])]),
+            );
+        }
+
+        return item;
+    };
+
+    return createHash("sha256")
+        .update(JSON.stringify(canonical(value)))
+        .digest("hex");
+}
+
+export function record(value, keys, required = keys) {
+    if (
+        !value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+        Object.keys(value).some((key) => !keys.includes(key)) ||
+        required.some((key) => !Object.hasOwn(value, key))
+    ) {
+        throw new DelegationError("Invalid closed delegation object");
+    }
+
+    return value;
+}
+
+export function text(value, max = 4000, empty = false) {
+    if (typeof value !== "string" || (!empty && !value.trim()) || value.length > max || value.includes("\0")) {
+        throw new DelegationError("Invalid delegation text");
+    }
+
+    return value;
+}
+
+function identifier(value) {
+    if (typeof value !== "string" || !/^[a-zA-Z0-9_-]{1,80}$/u.test(value)) {
+        throw new DelegationError("Invalid delegation identifier");
+    }
+
+    return value;
+}
+
+export function list(value, max, check) {
+    if (!Array.isArray(value) || value.length > max) {
+        throw new DelegationError("Invalid delegation list");
+    }
+
+    value.forEach(check);
+
+    return value;
+}
+
+export function integer(value, min, max) {
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        throw new DelegationError("Invalid delegation integer");
+    }
+
+    return value;
+}
+
+function validatePacketShape(packet) {
+    record(packet, ["objective", "requirements", "decisions", "nonGoals", "reason", "jobs"]);
+    text(packet.objective);
+    list(packet.requirements, 24, (item) => {
+        record(item, ["id", "text"]);
+        identifier(item.id);
+        text(item.text, 2000);
+    });
+    if (
+        !packet.requirements.length ||
+        new Set(packet.requirements.map((item) => item.id)).size !== packet.requirements.length
+    ) {
+        throw new DelegationError("Requirements must have unique identifiers");
+    }
+
+    list(packet.decisions, 24, (item) => text(item, 2000));
+    list(packet.nonGoals, 24, (item) => text(item, 2000));
+    record(packet.reason, ["benefit", "why", "parentWork"]);
+    if (!["independent_review", "parallel_analysis", "context_isolation"].includes(packet.reason.benefit)) {
+        throw new DelegationError("Delegation is limited to independent review or selected-source analysis");
+    }
+
+    text(packet.reason.why, 2000);
+    text(packet.reason.parentWork, 2000, packet.reason.benefit !== "parallel_analysis");
+    list(packet.jobs, LIMITS.batchJobs, (job) => {
+        record(job, ["id", "mode", "question", "context", "sources", "requirements"]);
+        identifier(job.id);
+        if (!["review", "scout"].includes(job.mode)) {
+            throw new DelegationError("Unsupported delegation mode");
+        }
+
+        text(job.question, 8000);
+        text(job.context, 128 * 1024, true);
+        list(job.sources, 200, (source) => text(source, 500));
+        list(job.requirements, packet.requirements.length, identifier);
+        if (
+            !job.requirements.length ||
+            new Set(job.requirements).size !== job.requirements.length ||
+            job.requirements.some((id) => !packet.requirements.some((requirement) => requirement.id === id))
+        ) {
+            throw new DelegationError("Each worker needs a unique subset of the packet requirement IDs");
+        }
+
+        if ((packet.reason.benefit === "independent_review") !== (job.mode === "review")) {
+            throw new DelegationError("The worker mode must match the declared delegation benefit");
+        }
+
+        if (!job.context.trim() && !job.sources.length) {
+            throw new DelegationError("A worker needs a frozen artifact or selected evidence to examine");
+        }
+
+        if (job.mode === "scout" && !job.sources.length) {
+            throw new DelegationError("A scout requires explicitly selected source files");
+        }
+    });
+    if (
+        !packet.jobs.length ||
+        new Set(packet.jobs.map((job) => job.id)).size !== packet.jobs.length ||
+        bytes(packet) > LIMITS.contextBytes
+    ) {
+        throw new DelegationError("Delegation packet exceeds its bound or repeats job identifiers");
+    }
+
+    if (new Set(packet.jobs.map((job) => job.question.trim().toLowerCase())).size !== packet.jobs.length) {
+        throw new DelegationError("Assign distinct worker questions instead of duplicate answers");
+    }
+}
+
+export function validatePacket(packet) {
+    validatePacketShape(packet);
+
+    return structuredClone(packet);
+}
+
+const bindingKeys = ["batchId", "jobId", "attemptId", "packetDigest", "generation", "resultRevision"];
+
+export function validateOperation(input) {
+    const operations = {
+        run: ["operation", "requestId", "packet"],
+        status: ["operation"],
+        collect: ["operation", "batchId", "afterCursor", "waitMs"],
+        follow_up: ["operation", "requestId", ...bindingKeys, "prompt"],
+        resolve: ["operation", "requestId", ...bindingKeys, "decision", "findings"],
+        cancel: ["operation", "requestId", "batchId", "jobId"],
+    };
+    if (!operations[input?.operation]) {
+        throw new DelegationError("Unsupported delegation operation");
+    }
+
+    const optional =
+        input.operation === "collect" ? ["afterCursor", "waitMs"] : input.operation === "cancel" ? ["jobId"] : [];
+    record(
+        input,
+        operations[input.operation],
+        operations[input.operation].filter((key) => !optional.includes(key)),
+    );
+    if (bytes(input) > LIMITS.contextBytes + 4096) {
+        throw new DelegationError("Delegation operation exceeds its bound");
+    }
+
+    for (const key of ["requestId", "batchId", "jobId", "attemptId"]) {
+        if (input[key] !== undefined) {
+            identifier(input[key]);
+        }
+    }
+
+    if (input.operation === "run") {
+        validatePacketShape(input.packet);
+    }
+
+    if (input.operation === "collect") {
+        integer(input.afterCursor ?? 0, 0, Number.MAX_SAFE_INTEGER);
+        integer(input.waitMs ?? 0, 0, 30_000);
+    }
+
+    if (["follow_up", "resolve"].includes(input.operation)) {
+        if (!/^[a-f0-9]{64}$/u.test(input.packetDigest)) {
+            throw new DelegationError("Invalid packet digest");
+        }
+
+        integer(input.generation, 0, Number.MAX_SAFE_INTEGER);
+        integer(input.resultRevision, 1, Number.MAX_SAFE_INTEGER);
+    }
+
+    if (input.operation === "follow_up") {
+        text(input.prompt, 8000);
+    }
+
+    if (input.operation === "resolve") {
+        if (!["accept", "discard", "needs_check"].includes(input.decision)) {
+            throw new DelegationError("Invalid parent disposition");
+        }
+
+        list(input.findings, 8, (finding) => {
+            record(finding, ["id", "decision"]);
+            identifier(finding.id);
+            if (!["confirmed", "rejected", "needs_check"].includes(finding.decision)) {
+                throw new DelegationError("Invalid finding disposition");
+            }
+        });
+    }
+
+    return structuredClone(input);
+}
+
+export function validateResult(result, { requirements, sources }) {
+    record(result, ["status", "answer", "requirements", "findings", "missing", "nextStep"]);
+    if (bytes(result) > LIMITS.resultBytes || !["complete", "partial", "needs_context"].includes(result.status)) {
+        throw new DelegationError("Invalid worker result size or status");
+    }
+
+    text(result.answer, 12_000, true);
+    text(result.nextStep, 2000, true);
+    list(result.missing, 16, (item) => text(item, 1000));
+    const sourceMap = new Map(sources.map((source) => [source.id, source]));
+    const evidence = (item) => {
+        record(item, ["sourceId", "lineStart", "lineEnd"]);
+        const source = sourceMap.get(item.sourceId);
+        if (!source) {
+            throw new DelegationError("Worker referenced an unknown source");
+        }
+
+        integer(item.lineStart, 1, source.lineCount);
+        integer(item.lineEnd, item.lineStart, source.lineCount);
+    };
+
+    list(result.requirements, requirements.length, (item) => {
+        record(item, ["id", "status", "evidence"]);
+        if (
+            !requirements.some((requirement) => requirement.id === item.id) ||
+            !["addressed", "unaddressed"].includes(item.status)
+        ) {
+            throw new DelegationError("Worker requirement coverage is invalid");
+        }
+
+        list(item.evidence, 8, evidence);
+    });
+    if (new Set(result.requirements.map((item) => item.id)).size !== requirements.length) {
+        throw new DelegationError("Worker must cover each requirement exactly once");
+    }
+
+    list(result.findings, 8, (finding) => {
+        record(finding, ["id", "claim", "confidence", "evidence", "contraryEvidence"]);
+        identifier(finding.id);
+        text(finding.claim, 2000);
+        if (!["observed", "inferred", "unverified"].includes(finding.confidence)) {
+            throw new DelegationError("Invalid finding confidence");
+        }
+
+        list(finding.evidence, 8, evidence);
+        list(finding.contraryEvidence, 8, evidence);
+        if (finding.confidence === "observed" && !finding.evidence.length) {
+            throw new DelegationError("Observed findings require a source reference");
+        }
+    });
+    if (new Set(result.findings.map((finding) => finding.id)).size !== result.findings.length) {
+        throw new DelegationError("Worker finding identifiers must be unique");
+    }
+
+    return structuredClone(result);
+}