@jitsusama/agentic-harness.core 0.1.0

package/dist/review/ask/identity.js

@@ -0,0 +1,134 @@
+/**
+ * What a participant id means, and keeping it meaning that.
+ *
+ * A finding's origin names the reviewer that raised it, and a
+ * reader trusts that name to identify one thing. Let an id be
+ * re-pointed at a different model halfway through and every origin
+ * recorded before the change quietly starts lying, with nothing on
+ * the record to say so. So an id that has produced findings is
+ * held to what it meant.
+ *
+ * The ledger is told the findings rather than going to look for
+ * them. What counts as attributed is a fact about a finding, and a
+ * module that had to know where findings are stored would be
+ * answerable to every future place they might be.
+ */
+/**
+ * Reduce a participant's config to the identity it claims.
+ *
+ * Absent fields are left out rather than set undefined, so two
+ * identities compare equal when they say the same thing, and a
+ * reader is never shown a key that was never configured.
+ */
+export function participantIdentity(role, participant) {
+    return {
+        id: participant.id,
+        role,
+        ...(participant.model === undefined ? {} : { model: participant.model }),
+        ...(participant.thinkingLevel === undefined
+            ? {}
+            : { thinkingLevel: participant.thinkingLevel }),
+        ...(participant.tools === undefined
+            ? {}
+            : { tools: [...participant.tools] }),
+        ...(participant.persona === undefined
+            ? {}
+            : { persona: participant.persona }),
+    };
+}
+/**
+ * Whether a finding names this id, as its author or as agreement.
+ *
+ * A consolidating pass records which reviewers raised the same
+ * thing, and those ids are as referenced as the author's: a
+ * release that ignored them would report that nothing points at an
+ * id while several findings name it.
+ */
+export function attributedTo(finding, id) {
+    const origin = finding.origin;
+    if (origin.kind !== "hand" && origin.reviewerId === id)
+        return true;
+    return finding.raisedBy?.includes(id) ?? false;
+}
+/** A fresh ledger, holding nothing. */
+export function createIdentityLedger() {
+    const identities = new Map();
+    return {
+        claim(role, participant, findings) {
+            const next = participantIdentity(role, participant);
+            const existing = identities.get(participant.id);
+            if (existing && !same(existing, next)) {
+                // An id nothing points at can be re-pointed in silence.
+                // The trail only matters where there is output to
+                // attribute, and refusing otherwise would make fixing a
+                // roster typo a chore.
+                if (findings.some((f) => attributedTo(f, participant.id))) {
+                    return { refusal: refuse(existing, next) };
+                }
+                identities.delete(participant.id);
+            }
+            identities.set(participant.id, next);
+            return { held: next };
+        },
+        release(id) {
+            return identities.delete(id);
+        },
+        held() {
+            return [...identities.values()];
+        },
+    };
+}
+/** Whether two identities say the same thing. */
+function same(left, right) {
+    return (left.id === right.id &&
+        left.role === right.role &&
+        left.model === right.model &&
+        left.thinkingLevel === right.thinkingLevel &&
+        left.persona === right.persona &&
+        sameTools(left.tools, right.tools));
+}
+/**
+ * Whether two tool palettes grant the same thing.
+ *
+ * Compared as sets: what a reviewer can reach is what changes its
+ * answers, and the order they were listed in does not. Refusing on
+ * a reordering would be a false alarm about a roster nobody
+ * meaningfully edited.
+ */
+function sameTools(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    if (left.length !== right.length)
+        return false;
+    const held = new Set(left);
+    return right.every((tool) => held.has(tool));
+}
+/**
+ * The refusal, which names both ways out.
+ *
+ * One is to use another id, which keeps the trail exact. The other
+ * is to release this one, which does not, and saying so plainly is
+ * what makes it a choice rather than a workaround someone finds
+ * later.
+ */
+function refuse(existing, next) {
+    return (`The id "${existing.id}" already means ${describe(existing)}, ` +
+        `and findings are attributed to it. Asking it to mean ` +
+        `${describe(next)} would change what those findings say about ` +
+        `who raised them. Use a different id for ${describe(next)}, or ` +
+        `release "${existing.id}" to accept that its findings become ` +
+        `ambiguous about which participant they came from.`);
+}
+/** An identity in words, for a sentence a person reads. */
+function describe(identity) {
+    const parts = [identity.role];
+    if (identity.persona)
+        parts.push(`persona ${identity.persona}`);
+    if (identity.model)
+        parts.push(`model ${identity.model}`);
+    if (identity.thinkingLevel)
+        parts.push(`thinking ${identity.thinkingLevel}`);
+    if (identity.tools)
+        parts.push(`tools ${identity.tools.join(", ")}`);
+    return parts.join(" · ");
+}

package/dist/review/ask/judge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Consolidating what a council said.
+ *
+ * A judge is one participant asked once, so this is much simpler
+ * than a council, and it is a separate round rather than a council of
+ * one for two reasons a reader downstream depends on.
+ *
+ * Its findings carry origin kind `judge`, which is what tells anyone
+ * reading them later that this pass consolidated rather than
+ * discovered. And its participant holds role `judge`, which is what
+ * the identity ledger uses to refuse letting one id be both: a reader
+ * of the origins would have no way to tell the consolidation from the
+ * thing it consolidated.
+ */
+import { type CouncilDeps } from "./council.js";
+import { type Participant } from "./identity.js";
+import { type AskRun, type RoundGiven } from "./run.js";
+/** Who consolidates, and what they are told. */
+export interface JudgeRequest {
+    judge: Participant;
+    prompt: string;
+    /** Distinguishes two rounds started in the same millisecond. */
+    seq: number;
+    /** Commit under review, which anchors claim when the tree is it. */
+    witness?: string;
+    /** Said when the tree the reviewers read was not that commit. */
+    unpinned?: string;
+    /** What the judge was handed, besides the change. */
+    given?: RoundGiven;
+}
+/** The run, and anything worth telling the caller. */
+export interface JudgeResult {
+    run: AskRun;
+    warnings: string[];
+}
+/** Ask a judge to consolidate, and record what it concluded. */
+export declare function runJudge(request: JudgeRequest, deps: CouncilDeps): Promise<JudgeResult>;

package/dist/review/ask/judge.js

@@ -0,0 +1,140 @@
+/**
+ * Consolidating what a council said.
+ *
+ * A judge is one participant asked once, so this is much simpler
+ * than a council, and it is a separate round rather than a council of
+ * one for two reasons a reader downstream depends on.
+ *
+ * Its findings carry origin kind `judge`, which is what tells anyone
+ * reading them later that this pass consolidated rather than
+ * discovered. And its participant holds role `judge`, which is what
+ * the identity ledger uses to refuse letting one id be both: a reader
+ * of the origins would have no way to tell the consolidation from the
+ * thing it consolidated.
+ */
+import { askOne } from "./council.js";
+import { alsoRecorded, harvestFindings } from "./harvest.js";
+import { participantIdentity } from "./identity.js";
+import { newRunId, whatItGave, whatItRead, } from "./run.js";
+/** Ask a judge to consolidate, and record what it concluded. */
+export async function runJudge(request, deps) {
+    const startedAt = deps.now();
+    const id = newRunId("judge", startedAt, request.seq);
+    const warnings = [];
+    // Written down before it is asked, for the reason a council is. A
+    // judge is cheaper than the round it consolidates and not cheap: a
+    // session that dies partway through leaves a reviewer directory on
+    // disk with nothing saying which change it belonged to or that it
+    // was ever a round, so the sweep takes it on the ordinary window
+    // while it holds the only copy of what was concluded.
+    //
+    // This callback was on the shared dependency type and honoured by
+    // one of the two runners that take it, so a caller keeping a ledger
+    // had its judge rounds silently left out of it.
+    try {
+        await deps.opened?.({
+            id,
+            round: "judge",
+            startedAt: startedAt.toISOString(),
+            participants: [participantIdentity("judge", request.judge)],
+            outcomes: [],
+            open: true,
+            // The provenance too, and a gate caught me leaving it out. An
+            // interrupted round is the one a reader has least context for,
+            // so recording it without what it read and what it was given
+            // is where the omission costs most rather than least.
+            ...whatItRead(request),
+            ...whatItGave(request),
+        });
+    }
+    catch {
+        // Guarded like the council's, and for the same reason: a
+        // bookkeeping callback that throws must not take down the round
+        // it was recording. The cost is that an interrupted judge may
+        // not be findable, which is what it was before this existed.
+    }
+    // Reported, which this round did not used to be. A judge is one
+    // participant, so it never went through the roster path that does the
+    // reporting, and nothing here did it instead: a consolidation of sixty
+    // findings ran to completion showing no sign of life. `askOne` also
+    // folds a thrown runner into a reported failure, which is why the
+    // try/catch that used to say so is gone rather than kept beside it.
+    const answer = await askOne(request.judge, request.prompt, id, deps);
+    const outcome = await (async () => {
+        if ("failure" in answer) {
+            return {
+                participantId: request.judge.id,
+                findingIds: [],
+                failure: answer.failure,
+            };
+        }
+        const origin = {
+            kind: "judge",
+            runId: id,
+            reviewerId: request.judge.id,
+        };
+        // A judge writes findings down as it goes for the same reason a
+        // reviewer does, and it runs against every reviewer's answer at
+        // once, so it is the participant most likely to run long.
+        //
+        // Only as a fallback, though, unlike a reviewer's. A judge's
+        // job is deciding what survives, so a finding it recorded early
+        // and left out of its consolidation was dropped on purpose, and
+        // unioning would overrule the one participant paid to choose.
+        // When it produced no consolidation at all, what it wrote down
+        // on the way is all there is.
+        const said = harvestFindings(answer.text, origin, request);
+        const harvest = said.findings.length > 0
+            ? said
+            : alsoRecorded(said, answer.recorded, origin, request);
+        for (const warning of [...harvest.warnings, ...(answer.notes ?? [])]) {
+            warnings.push(`${request.judge.id}: ${warning}`);
+        }
+        const recorded = harvest.findings.length === 0 ? [] : await deps.record(harvest.findings);
+        // Counted from what was filed rather than from the answer, the same
+        // rule the roster rounds settle by: a finding that would not parse
+        // never became one, and saying otherwise on the way past would
+        // overcount the round in the only place anyone sees it live.
+        deps.progress?.recorded(request.judge.id, recorded.length);
+        return {
+            participantId: request.judge.id,
+            findingIds: recorded.map((finding) => finding.id),
+            // A judge can be stopped exactly as a reviewer can, and a
+            // round that does not record it reports the same lie the
+            // council round was fixed for: a participant taken away
+            // mid-sentence, filed as one that answered.
+            ...(answer.stopped === undefined ? {} : { stopped: answer.stopped }),
+            ...(answer.answerPath === undefined
+                ? {}
+                : { answerPath: answer.answerPath }),
+            ...(answer.usage === undefined ? {} : { usage: answer.usage }),
+        };
+    })();
+    // The board is about to be replaced by the round's own answer, and a
+    // stale one outlives the thing it described.
+    deps.progress?.finish();
+    return {
+        run: {
+            id,
+            round: "judge",
+            startedAt: startedAt.toISOString(),
+            participants: [participantIdentity("judge", request.judge)],
+            outcomes: [outcome],
+            // The same commit the findings above are anchored against,
+            // said on the round as well. It was used and not recorded,
+            // so every judge round in the ledger could anchor a finding
+            // honestly and still not say what it had judged: sixteen of
+            // sixteen, beside councils that all could.
+            //
+            // The ledger is the reason, and the only one. A judge round
+            // is never left open, so no collect will read this, and
+            // claiming otherwise would be justifying a fact with a path
+            // that cannot be taken. What it answers is a reader asking
+            // what a round was formed against, which until now the
+            // record could not say for three kinds out of four.
+            ...whatItRead(request),
+            ...whatItGave(request),
+        },
+        warnings,
+    };
+}

package/dist/review/ask/persona.d.ts

@@ -0,0 +1,84 @@
+/**
+ * A review lens, authored as prose.
+ *
+ * A persona is what makes six reviewers worth more than one reviewer
+ * asked six times: they read the same change looking for different
+ * things. The lens is prose because that is what shapes a reader, and
+ * because a lens somebody can argue with in a text editor is a lens
+ * that gets better.
+ *
+ * The frontmatter is identity and carries no mechanism. Which model a
+ * persona runs on, how hard it thinks and what tools it can reach are
+ * decisions about cost and capability, and they belong in the roster
+ * beside the other participants rather than buried in a charter. The
+ * same lens at two thinking levels is two roster entries, not two
+ * files.
+ *
+ * Reading the file is somebody else's job. This module is handed the
+ * text, so the analysis can be tested without a directory and the
+ * question of where personas live stays where the answer differs.
+ */
+import type { Participant } from "./identity.js";
+import type { Roster } from "./roster.js";
+/** A lens a reviewer reads through. */
+export interface Persona {
+    /** Stable id, which is the file's name. */
+    id: string;
+    name: string;
+    description: string;
+    /** The charter prose: the file body, frontmatter stripped. */
+    charter: string;
+}
+/** A persona, or why it could not be read. */
+export type PersonaParse = {
+    persona: Persona;
+} | {
+    refusal: string;
+};
+/** Where a charter comes from, by persona id. */
+export type CharterLookup = (personaId: string) => string | undefined;
+/** A participant and the charter it reads through, if any. */
+export interface PersonaBinding {
+    participant: Participant;
+    charter?: string;
+}
+/** Every participant bound to its charter, or why not. */
+export type PersonaBind = {
+    bindings: PersonaBinding[];
+} | {
+    refusal: string;
+};
+/**
+ * Read a persona file.
+ *
+ * The id comes from the caller rather than the file, because the id
+ * has to be unique and only the directory can enforce that: two files
+ * cannot share a name, and nothing written inside a file can promise
+ * the same.
+ */
+export declare function parsePersona(id: string, text: string): PersonaParse;
+/**
+ * Bind every participant in a roster to the charter it names.
+ *
+ * A missing persona is a refusal rather than a fallback. A reviewer
+ * meant to be a security lens that silently became a generic one still
+ * files its findings under the name "security", and whoever reads them
+ * afterwards weighs them as a specialist's. Better to say the file is
+ * missing than to quietly answer a different question.
+ */
+export declare function bindPersonas(roster: Roster, lookup: CharterLookup): PersonaBind;
+/**
+ * The frontmatter fields and the body after them, or nothing.
+ *
+ * Exported within the module rather than kept private, because the
+ * repo-agent reader needs the same split and needs the raw fields
+ * besides: it reports which of them it declined to adopt, and a parse
+ * that hands back only a `Persona` has already thrown those away.
+ * Deliberately not in the barrel, since the frontmatter contract is
+ * this module's business and not a consumer's.
+ */
+export declare function splitFrontmatter(text: string): {
+    fields: Record<string, string>;
+    block: string;
+    body: string;
+} | undefined;

package/dist/review/ask/persona.js

@@ -0,0 +1,127 @@
+/**
+ * A review lens, authored as prose.
+ *
+ * A persona is what makes six reviewers worth more than one reviewer
+ * asked six times: they read the same change looking for different
+ * things. The lens is prose because that is what shapes a reader, and
+ * because a lens somebody can argue with in a text editor is a lens
+ * that gets better.
+ *
+ * The frontmatter is identity and carries no mechanism. Which model a
+ * persona runs on, how hard it thinks and what tools it can reach are
+ * decisions about cost and capability, and they belong in the roster
+ * beside the other participants rather than buried in a charter. The
+ * same lens at two thinking levels is two roster entries, not two
+ * files.
+ *
+ * Reading the file is somebody else's job. This module is handed the
+ * text, so the analysis can be tested without a directory and the
+ * question of where personas live stays where the answer differs.
+ */
+/** The line that opens and closes a frontmatter block. */
+const FENCE = "---";
+/**
+ * Read a persona file.
+ *
+ * The id comes from the caller rather than the file, because the id
+ * has to be unique and only the directory can enforce that: two files
+ * cannot share a name, and nothing written inside a file can promise
+ * the same.
+ */
+export function parsePersona(id, text) {
+    const split = splitFrontmatter(text);
+    if (split === undefined) {
+        return {
+            refusal: `The persona "${id}" has no frontmatter block, so it names no lens. A persona opens with ${FENCE}, a name and a description, and closes with ${FENCE} before its charter.`,
+        };
+    }
+    const name = split.fields.name;
+    if (name === undefined || name === "") {
+        return {
+            refusal: `The persona "${id}" gives no name in its frontmatter, so there is nothing to call it.`,
+        };
+    }
+    const description = split.fields.description;
+    if (description === undefined || description === "") {
+        return {
+            refusal: `The persona "${id}" gives no description in its frontmatter. The description is how somebody choosing a roster knows what this lens is for.`,
+        };
+    }
+    const charter = split.body.trim();
+    if (charter === "") {
+        // A named lens with nothing behind it is worse than no persona:
+        // the roster reads as though a specialist is on it.
+        return {
+            refusal: `The persona "${id}" has an empty charter, so it is a name for a lens that does not exist. The body of the file is what shapes the reviewer.`,
+        };
+    }
+    return { persona: { id, name, description, charter } };
+}
+/**
+ * Bind every participant in a roster to the charter it names.
+ *
+ * A missing persona is a refusal rather than a fallback. A reviewer
+ * meant to be a security lens that silently became a generic one still
+ * files its findings under the name "security", and whoever reads them
+ * afterwards weighs them as a specialist's. Better to say the file is
+ * missing than to quietly answer a different question.
+ */
+export function bindPersonas(roster, lookup) {
+    const participants = [
+        ...roster.reviewers,
+        ...(roster.judge === undefined ? [] : [roster.judge]),
+    ];
+    const bindings = [];
+    for (const participant of participants) {
+        if (participant.persona === undefined) {
+            bindings.push({ participant });
+            continue;
+        }
+        const charter = lookup(participant.persona);
+        if (charter === undefined) {
+            return {
+                refusal: `The participant "${participant.id}" names the persona "${participant.persona}", and no such persona could be read. Add it, or drop the persona from this participant: running it without its lens would file generic findings under a specialist's name.`,
+            };
+        }
+        bindings.push({ participant, charter });
+    }
+    return { bindings };
+}
+/**
+ * The frontmatter fields and the body after them, or nothing.
+ *
+ * Exported within the module rather than kept private, because the
+ * repo-agent reader needs the same split and needs the raw fields
+ * besides: it reports which of them it declined to adopt, and a parse
+ * that hands back only a `Persona` has already thrown those away.
+ * Deliberately not in the barrel, since the frontmatter contract is
+ * this module's business and not a consumer's.
+ */
+export function splitFrontmatter(text) {
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== FENCE)
+        return undefined;
+    const close = lines.findIndex((line, at) => at > 0 && line.trim() === FENCE);
+    if (close === -1)
+        return undefined;
+    const fields = {};
+    for (const line of lines.slice(1, close)) {
+        const at = line.indexOf(":");
+        if (at === -1)
+            continue;
+        const key = line.slice(0, at).trim();
+        if (key === "")
+            continue;
+        fields[key] = line.slice(at + 1).trim();
+    }
+    // The block verbatim as well as the fields, so a reader that wants
+    // to parse it properly finds the fences with the same rule the body
+    // was found with. Two rules for one boundary is a gap between them,
+    // and a gap between the fields and the body is text that shows up in
+    // neither the listing nor the frontmatter and heads the charter.
+    return {
+        fields,
+        block: lines.slice(1, close).join("\n"),
+        body: lines.slice(close + 1).join("\n"),
+    };
+}

package/dist/review/ask/progress.d.ts

@@ -0,0 +1,117 @@
+/**
+ * What an ask round is doing while it does it.
+ *
+ * A council fans its roster out concurrently, which means the useful
+ * minutes of a round are minutes in which nothing is returned. A
+ * caller with no way to watch cannot tell a roster that is working
+ * from one that has hung, and the difference matters most when it is
+ * six subprocesses deep.
+ *
+ * The library emits events and holds no view. It also cannot see a
+ * subprocess: activity arrives because whoever implements `ask`
+ * reports it, which is what keeps this side free of any knowledge of
+ * streams, terminals or pi's wire format.
+ */
+import type { Participant } from "./identity.js";
+/**
+ * Where one participant has got to.
+ *
+ * Five, because a reviewer somebody stopped is not a reviewer that
+ * answered. With four states a cancelled one kept the mark and the
+ * colour of success, so the panel said the round had gone well at the
+ * exact moment somebody was telling it otherwise.
+ */
+export type AskProgressState = "pending" | "running" | "answered" | "cancelled" | "failed";
+/** One participant's row, as a reporter would draw it. */
+export interface AskProgressEntry {
+    readonly participantId: string;
+    /**
+     * Which model is answering, when the participant named one.
+     *
+     * Carried for the panel to show, because on a roster of seven personas
+     * the model is what tells you whether the slow one is slow for a
+     * reason. It is on the participant already; a reporter that dropped it
+     * would have to be handed the roster a second time to draw a row.
+     */
+    readonly model?: string;
+    readonly state: AskProgressState;
+    /** What it is doing right now, or empty once it has settled. */
+    readonly activity: string;
+    /**
+     * When it was sent away, in epoch milliseconds.
+     *
+     * A round is silent for a long time and the honest question a
+     * watcher has is how long this one has been going. Recorded on
+     * the row rather than computed by whoever draws, so every
+     * surface answers it the same way and a row that has settled
+     * still says how long it took.
+     */
+    readonly startedAtMs?: number;
+    /** When it settled, however it settled. */
+    readonly settledAtMs?: number;
+    /** Findings recorded from it, once they have been numbered. */
+    readonly findings?: number;
+    /** Why it failed, when it did. */
+    readonly reason?: string;
+}
+/**
+ * Told what is happening, in the order it happens.
+ *
+ * Every method returns nothing and must not throw: a reporter that
+ * fails should never take a round down with it.
+ */
+export interface AskProgress {
+    /** The whole roster, before anything runs, so a reporter can size itself. */
+    start(participants: readonly Participant[]): void;
+    /** This participant is away. */
+    started(participantId: string): void;
+    /** What it is doing right now. */
+    activity(participantId: string, what: string): void;
+    /** It answered. Its findings have not been counted yet. */
+    answered(participantId: string): void;
+    /** It failed, and why. */
+    failed(participantId: string, reason: string): void;
+    /**
+     * Somebody stopped it.
+     *
+     * Separate from failing, because it is the one settled state that is
+     * not news about the change. It outranks a later answer: the runner
+     * can report a reviewer home after the kill reached the panel, and
+     * repainting that row green loses the only thing the watcher knew.
+     */
+    cancelled(participantId: string): void;
+    /** Its findings have landed and been numbered. */
+    recorded(participantId: string, findings: number): void;
+    /** The round is over. */
+    finish(): void;
+}
+/**
+ * Record and report each reply in turn, in roster order.
+ *
+ * Both rounds settle their replies the same way and differ only in how
+ * a reply is filed, so the reporting lives here rather than in each.
+ * That is not tidiness: the stack round already shipped without it,
+ * because the reporting was two lines a caller had to remember, and
+ * the round that reports nothing is the longest one there is.
+ *
+ * Sequential and in roster order deliberately, which is what makes
+ * finding numbers deterministic. Recording concurrently would hand out
+ * ids in completion order.
+ */
+export declare function settleReplies<Reply, Outcome>(replies: readonly Reply[], file: (reply: Reply) => Promise<Outcome>, count: (outcome: Outcome) => {
+    participantId: string;
+    findings: number;
+}, progress: AskProgress | undefined): Promise<Outcome[]>;
+/** An observer that does nothing, for a caller that does not care. */
+export declare const noAskProgress: AskProgress;
+/**
+ * An observer that folds what it is told into rows.
+ *
+ * Every reporter needs this same fold, so it lives here rather than
+ * being written again per surface. `entries` is a snapshot: read it
+ * whenever you want to draw.
+ */
+export declare function trackAskProgress(now?: () => number): {
+    progress: AskProgress;
+    entries(): AskProgressEntry[];
+};