@jitsusama/agentic-harness.core 0.1.0

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

@@ -0,0 +1,435 @@
+/**
+ * What was asked of whom, and what came back.
+ *
+ * A run is a record rather than a working state: it says who was
+ * asked, in which pass, and what each of them came back with. A
+ * finding points at its run by id, so a run that got edited under
+ * one would change what an already-recorded finding means. Nothing
+ * here mutates; substituting an outcome returns a new run.
+ *
+ * The counts are kept as a function rather than fields, because a
+ * stored count and a stored list of outcomes are two things that
+ * can disagree, and only one of them is the evidence.
+ */
+import type { AskStop } from "./council.js";
+import type { ParticipantIdentity } from "./identity.js";
+import type { GuidanceState } from "./prompt.js";
+/** Which pass of a review this was. */
+export type AskRound = "council" | "judge" | "critique" | "audit"
+/** A council that saw the whole stack rather than one change. */
+ | "stack";
+/** What one participant's run cost, where the runner said. */
+export interface AskUsage {
+    tokens?: number;
+    cost?: number;
+}
+/** What one participant came back with. */
+export interface ParticipantOutcome {
+    participantId: string;
+    /**
+     * Findings this participant raised, by the id the store gave
+     * them. Held as ids rather than findings so the run does not
+     * become a second copy of them that can fall out of step.
+     */
+    findingIds: number[];
+    /** Why nothing came back, when nothing did. */
+    failure?: string;
+    /**
+     * The conditions this attempt ran under, where the round's may
+     * not describe it.
+     *
+     * Absent means the round's, which is every outcome a round asked
+     * for itself. A retry is the case that needs it: it re-asks one
+     * participant now and substitutes the answer into a round that may
+     * have been recorded before any of this existed, so the round's
+     * claim covers the outcomes it originally collected and not this
+     * one. Writing this attempt's conditions onto the round instead
+     * would claim them for reviewers that never ran under them, and
+     * saying nothing would lose the one fact the retry does know.
+     */
+    given?: RoundGiven;
+    /**
+     * Something true of the session rather than of this participant.
+     *
+     * Stated by whatever dispatched the round, since only that side
+     * can tell a broken session from a broken reviewer.
+     */
+    advisory?: string;
+    /**
+     * Which limit took this reviewer away, when one did.
+     *
+     * Recorded even when findings came back, because a stopped
+     * reviewer that raised nine findings had a tenth in hand, and a
+     * reader deciding whether the pass was complete needs to know the
+     * difference between nine and nine-so-far.
+     */
+    stopped?: AskStop;
+    /**
+     * Where this participant's answer was kept, verbatim.
+     *
+     * Recorded rather than derived from the ids, because a path that
+     * no longer resolves is honest history: it says an answer was kept
+     * here and has since been reclaimed, where a derived path would
+     * claim one that may never have existed.
+     */
+    answerPath?: string;
+    usage?: AskUsage;
+}
+/** One pass of asking, and its result. */
+export interface AskRun {
+    id: string;
+    round: AskRound;
+    startedAt: string;
+    /** Who was asked, in the order the roster named them. */
+    participants: ParticipantIdentity[];
+    /** What came back. May be shorter than the roster mid-run. */
+    outcomes: ParticipantOutcome[];
+    /**
+     * This round was written down before it asked anybody, and has
+     * not been settled since.
+     *
+     * Present only while that is true, rather than inferred from a
+     * missing settled time, because absence is the state everything
+     * else already has. Every round recorded before this existed,
+     * and every judge, critique, audit and stack round, carries no
+     * such field and never will, so an alarm keyed on absence would
+     * have declared the entire review history of every change
+     * abandoned the first time anybody asked.
+     *
+     * One producer, one meaning: a council that opened and whose
+     * session did not live to close it. Its reviewers' answers may
+     * still be on disk under this id, and this is the only thing
+     * that says to go looking.
+     */
+    open?: true;
+    /**
+     * Given up on by a person, rather than finished.
+     *
+     * There are three states here, not two, and the third cannot be
+     * spelled as the absence of the second. A round closed because
+     * nothing was running and nothing was left behind is not a
+     * council that reported: it has no outcomes and no findings, so
+     * merely clearing `open` would make it the most recent finished
+     * council on the change, and `latest` would hand it to the next
+     * judge, critique and retry. Each would consolidate nothing and
+     * report that the council found nothing, while the real council
+     * sat one entry behind, unreachable.
+     *
+     * Marked by something present rather than inferred from something
+     * missing, for the same reason `open` is.
+     */
+    closed?: true;
+    /**
+     * What the reviewers were reading, when the round pinned one.
+     *
+     * Written down because an interrupted round is collected from
+     * disk afterwards, and a finding harvested then has to anchor
+     * exactly as it would have live. Everything else a collect needs
+     * is in the reviewer's own answer; this is not, so a round that
+     * did not record it cannot be collected faithfully.
+     */
+    witness?: string;
+    /**
+     * Said when the tree the reviewers read was not that commit.
+     *
+     * Every round records a witness, and a round that fell back to
+     * the caller's checkout records one too, so without this the
+     * ledger claims a fidelity the round did not have. The caveat
+     * itself was only ever handed to the session that started the
+     * round, which leaves a round collected later, whose reader has
+     * nothing but this file, told nothing at all.
+     *
+     * It happens. Two councils fell back because a worktree of that
+     * name already existed, and between them they returned fifty-nine
+     * findings formed against whatever the checkout happened to be.
+     */
+    unpinned?: string;
+    /**
+     * What its reviewers were handed, besides the change itself.
+     *
+     * A reviewer's answer depends on what it was given, and a run that
+     * records only who was asked and what they read cannot be compared
+     * with one recorded under a different configuration. Two councils a
+     * week apart, one before reviewers were isolated and one after,
+     * left records that read identically while being worth different
+     * amounts.
+     *
+     * Absent on every round that predates it, which is most of the
+     * ledger, and absent has to keep meaning nobody said: a default
+     * filled in by a builder would make the whole history claim a
+     * configuration nobody can check.
+     */
+    given?: RoundGiven;
+}
+/**
+ * What a round handed its reviewers, besides the change.
+ *
+ * Not who they were, which the participants already carry, and not
+ * what they read, which the witness does. This is the part that comes
+ * from neither the roster nor the repository under review: the
+ * conditions the round chose to run them under.
+ */
+export interface RoundGiven {
+    /**
+     * They were spawned asking for none of the ambient setup.
+     *
+     * What was asked for, not everything that was thereby excluded.
+     * An extension registered as a subagent default still reaches
+     * every child, isolation or not, because that is how a credentials
+     * helper gets to a reviewer that needs one, and nothing here can
+     * name what the operator registered. So this says the round asked
+     * for isolation and stops short of saying the reviewer had nothing
+     * but the round's own material.
+     *
+     * Required, not optional. There are three states and the whole
+     * field carries the first: a run with no `given` at all is one
+     * nobody recorded, which is most of the ledger. Within a record
+     * that exists, saying nothing here would be a fourth state meaning
+     * the same as the first, in a place a reader has already been
+     * promised an answer.
+     */
+    isolated: boolean;
+    /**
+     * The repo's own written conventions, where the round quoted them.
+     *
+     * The path and not the text. A reader chasing a finding needs to
+     * know which file was folded into the prompt and whether the change
+     * itself had written it; the bytes are in the tree at the witness,
+     * and copying tens of thousands of characters into every run record
+     * would cost more than the whole ledger.
+     */
+    quoted?: {
+        path: string;
+        edited: GuidanceState;
+        /** Only the first part of the file reached the prompt. */
+        cut?: true;
+        /**
+         * Named to the reviewer, and not reproduced.
+         *
+         * Text that cannot be fenced is not quoted at all, since unquoted
+         * it reads as the round's own words. Without this the record
+         * claims a quotation the reviewer never saw, which is the
+         * indistinguishability the whole field exists to remove.
+         */
+        withheld?: true;
+    };
+}
+/**
+ * What a round was given, in the shape a run records it.
+ *
+ * @see whatItRead
+ *
+ * The counterpart of `whatItRead`, and one helper for the same reason:
+ * it is one fact, six builders write it, and the last fact that had to
+ * reach all six reached four.
+ */
+export declare function whatItGave(request: {
+    given?: RoundGiven;
+}): {
+    given?: RoundGiven;
+};
+/** How a run went, in counts. */
+export interface RunSummary {
+    asked: number;
+    answered: number;
+    failed: number;
+    /**
+     * Asked, and not yet reported either way.
+     *
+     * Only ever non-zero for a round still open. A round that has
+     * settled has heard from everybody it is going to hear from, so a
+     * participant with no outcome there has dropped.
+     */
+    pending: number;
+    findings: number;
+    /**
+     * What the round burned, across everybody who reported it.
+     *
+     * Absent rather than zero when nobody reported, because a round of
+     * participants that said nothing about usage is not a free round,
+     * and a zero here would say it was.
+     *
+     * A failed participant counts. It was billed for whatever it
+     * burned before it died, and leaving those out would make the
+     * expensive failures look like the cheap ones, which is backwards:
+     * a reviewer that ran fifteen minutes and produced nothing is the
+     * most expensive kind there is.
+     */
+    tokens?: number;
+    /** What it came to in money, on the same terms as `tokens`. */
+    cost?: number;
+    /**
+     * Whether anybody who was asked is missing from those totals.
+     *
+     * A round where six of seven reported is not a round that cost the
+     * sum of six, and printing one as the other is the same lie as
+     * printing zero for a round nobody priced. The participants most
+     * likely to be missing are the ones that died, which are the dear
+     * ones, so the error runs the wrong way.
+     */
+    partlyPriced?: boolean;
+}
+/**
+ * Name a run.
+ *
+ * The round leads, so a bare id says what pass it was without
+ * anything having to look it up. The timestamp sorts. The sequence
+ * is part of the name rather than a tiebreak applied later, because
+ * two runs inside one millisecond would otherwise collide and make
+ * one run's findings unreachable, and it is zero-padded so it keeps
+ * sorting as text rather than putting 10 before 9.
+ */
+export declare function newRunId(round: AskRound, at: Date, seq: number): string;
+/**
+ * What is wrong with the session rather than with the reviewers.
+ *
+ * Measured. Pi upgraded mid-session and deleted the versioned install
+ * directory the running session pins its children to, so every
+ * reviewer died on dispatch. The runner diagnosed it correctly and
+ * put the same sentence on all seven, and the round printed it seven
+ * times as though seven separate things had gone wrong.
+ *
+ * The repetition is not the cost. Seven failures beside a retry hint
+ * read as seven flaky reviewers, and retrying is the one thing that
+ * cannot work: it fails identically until the session restarts.
+ *
+ * Read off the outcome rather than sniffed out of the message. This
+ * matched a prefix first, which made one library string-match another
+ * library's prose, and both are free to reword: the diagnosis is a
+ * fact the dispatching side knows, so it is carried as one.
+ *
+ * One participant is enough. A stale install kills every reviewer it
+ * reaches, and a round where one dispatch raced the deletion is
+ * exactly as unrecoverable by retry as one where all seven did.
+ */
+export declare function staleRuntimeAdvisory(run: AskRun): string | undefined;
+/**
+ * One line for each participant that failed, without saying the same
+ * paragraph twice.
+ *
+ * The roll call has to survive an advisory: a reader needs to see who
+ * was asked and that none of them answered, or the round looks like it
+ * never ran. What it does not need is the advisory repeated under
+ * every name, which is what hoisting a sentence already on every
+ * outcome would otherwise produce, one copy longer than before.
+ *
+ * What was hoisted is told rather than worked out again. Deciding it
+ * twice means the two can disagree, and the way they disagree is the
+ * worst of both: a caller that suppressed the advisory gets a roll
+ * call of reviewers pointing at a line that is not there.
+ */
+export declare function failureLines(run: AskRun, hoisted?: string): string[];
+/**
+ * What became of each participant a limit took away.
+ *
+ * The round already records that a reviewer was stopped and where its
+ * answer was kept, and recorded both without ever printing them, which
+ * is most of the way to losing the answer regardless: nobody opens a
+ * ledger they have no reason to open. One line each, naming who, what
+ * stopped them and where to read what they said.
+ */
+export declare function stoppedNotes(run: AskRun): string[];
+/**
+ * How a run went.
+ *
+ * Someone asked with no outcome at all counts as failed rather than
+ * as pending, since a run being reported on has finished and a
+ * participant that never reported is one that dropped. Answering
+ * nothing is an answer: a reviewer that read the change and had no
+ * complaint is not a failure, and counting it as one would make a
+ * clean review look broken.
+ *
+ * Unless the round is still open, where the same silence means the
+ * opposite. Nobody has asked those reviewers for anything yet: a
+ * started round that has recorded nothing summarised as seven failed
+ * out of seven, and every sentence built on that read as an
+ * accusation against reviewers who were at that moment working.
+ */
+export declare function runSummary(run: AskRun): RunSummary;
+/** What a round was told about the tree it would read. */
+export interface TreeRead {
+    /**
+     * Commit under review, which anchors claim when the tree was it.
+     *
+     * Not "the commit the anchors are formed against", which is what
+     * this said while being true only of a pinned round. An unpinned
+     * round records the commit here and claims it nowhere else.
+     */
+    witness?: string;
+    /** Said when the tree the reviewers read was not that commit. */
+    unpinned?: string;
+}
+/**
+ * What a round read, in the shape a run records it.
+ *
+ * One helper rather than a conditional spread per builder, because
+ * these two are one fact. Recording the commit without the caveat is
+ * the failure this exists to stop: the run then claims the reviewers
+ * read the change when they read whatever the caller had checked out.
+ * Six sites spread the commit by hand, and it took until the ledger
+ * was counted to notice that half of them recorded nothing at all.
+ */
+export declare function whatItRead(read: TreeRead): TreeRead;
+/**
+ * The commit an anchor from this round may claim.
+ *
+ * An anchor's witness means the commit it was formed against, and the
+ * substrate reads it to tell a thread the backend kept from one a
+ * force-push stranded. A round that fell back to the caller's
+ * checkout was never formed against the commit under review, so
+ * stamping it there makes the substrate confidently wrong in exactly
+ * the case the field exists to disambiguate.
+ *
+ * Nothing, then, rather than the commit: not knowing which tree a
+ * finding came from is the truth, and an anchor that says so degrades
+ * to what anchors did before witnesses existed. The run keeps both
+ * facts, because what the change is at and what the reviewers read
+ * are two different things and the ledger wants each.
+ */
+export declare function anchorWitness(read: TreeRead): string | undefined;
+/** The identity a run asked under this id, if it asked one. */
+export declare function askedOf(run: AskRun, participantId: string): ParticipantIdentity | undefined;
+/**
+ * Why a retry may not be given new settings, if it may not.
+ *
+ * A retry re-asks one participant and substitutes the answer into a
+ * round that already recorded who it asked and what each was set to.
+ * Asking on a different model puts one participant's answer into a run
+ * whose ledger names another, and the identity ledger cannot catch it,
+ * because the substitution keeps the held run's participants: nothing
+ * ever claims the new configuration.
+ *
+ * The clocks are the exception, and they are the reason somebody is
+ * retrying at all. How long a reviewer was allowed does not change
+ * what its findings mean, the ledger does not record it against the
+ * participant, and a reviewer stopped by a wall is refused the retry
+ * outright unless that wall moves. Refusing the one setting that makes
+ * the retry worth running would leave editing a committed file as the
+ * only road.
+ *
+ * A predicate rather than a branch inside the tool, so the rule can be
+ * read and tested without a round on disk to retry.
+ */
+export declare function retryCannotResettle(who: Record<string, object> | undefined, run: {
+    id: string;
+}, participantId: string): string | undefined;
+/**
+ * Replace one participant's outcome, returning a new run.
+ *
+ * This is what a retry does. The outcome keeps its position, since
+ * a retry that moved a reviewer to the end would reorder every
+ * report of the run for no reason a reader could see, and a
+ * participant who had no outcome yet gets one appended.
+ *
+ * Substituting for somebody outside the roster throws rather than
+ * refusing softly: it would make the run claim it asked somebody it
+ * never did, and no caller has a sensible way to carry on from
+ * that.
+ *
+ * What this attempt read is required rather than optional, since
+ * omitting it means "the same tree the round had", which is the most
+ * optimistic reading available and the wrong default for the case
+ * that matters: a retry that fell back leaves the round less faithful
+ * than it was. Pass an empty record to say there is nothing to add.
+ */
+export declare function substituteOutcome(run: AskRun, outcome: ParticipantOutcome, read: TreeRead): AskRun;