@jitsusama/agentic-harness.core 0.1.0

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

@@ -0,0 +1,89 @@
+/**
+ * Reading what a model actually sent.
+ *
+ * A model answers in prose with JSON somewhere inside it, however
+ * firmly it was asked not to, and every round has to cope with the
+ * same handful of shapes. This is shared rather than copied because it
+ * is one concept and not two that merely look alike: if models change
+ * how they wrap an answer, every round is wrong in the same way at the
+ * same time, and there should be one place to fix it.
+ */
+/**
+ * The JSON object in an answer, wherever it is.
+ *
+ * Tries the whole answer, then a fenced block, then the widest
+ * brace-delimited span. Widest rather than first, because a model that
+ * reasons before answering often writes a smaller object earlier in
+ * the prose. The fence is tried before the span because a model
+ * quoting code in its reasoning puts braces in the prose, and the span
+ * then swallows the prose and parses as nothing.
+ */
+export declare function findJson(text: string): Record<string, unknown> | undefined;
+/** An answer, and whether it is all of one. */
+export interface AnswerRead {
+    /** The object the answer carried, whole or salvaged. */
+    readonly parsed: Record<string, unknown> | undefined;
+    /** Whether what came back is the surviving part of a longer answer. */
+    readonly truncated: boolean;
+}
+/**
+ * What a reviewer said, taking the part that survived over nothing.
+ *
+ * Every round reads its answer the same way and can be interrupted in
+ * the same place, so the fallback belongs here rather than four times
+ * over. A caller that must know it is holding half an answer reads
+ * `truncated`, and every caller must, because a partial answer that
+ * does not say so is a reviewer that appears to have found less than
+ * it did.
+ */
+export declare function readAnswer(text: string, key: string): AnswerRead;
+/**
+ * How a round says an answer stopped early.
+ *
+ * Worth wording once. The reader has to come away knowing that the
+ * gap is unmeasured, or a truncated answer gets read as a thorough
+ * one, which is how a round can look complete while missing the
+ * finding that mattered.
+ */
+export declare const ANSWER_WAS_CUT_OFF = "This answer was cut off partway through, so what follows is what survived: everything the reviewer completed before it stopped, and not the entry it was in the middle of. There is no way to tell how much more it would have sent, so treat an absence here as unknown rather than as nothing to report.";
+/**
+ * What an answer still holds after it was cut off.
+ *
+ * A reviewer stopped at its budget stops wherever it had got to,
+ * which for a long answer is partway through the findings array. The
+ * text will not parse, and dropping it loses every finding that did
+ * arrive whole along with the one that did not.
+ *
+ * Nothing is repaired. Each entry of the named array is taken on its
+ * own and handed to the parser by itself: one that finished parses,
+ * one that did not, does not. An earlier version cut the text at a
+ * point where everything open could be closed and let the closers do
+ * the rest, which is a property of the syntax rather than of the
+ * entries. Every real finding holds a nested location, so an entry
+ * interrupted after that location closed satisfied the rule, and a
+ * half-written finding came back looking exactly like a whole one
+ * with its argument missing. A finding completed by guesswork cannot
+ * be told from one the reviewer made, which is the one outcome worth
+ * refusing outright.
+ *
+ * Anchored on the key rather than the first brace, which is also why
+ * a brace in the reviewer's prose no longer costs the answer: `findJson`
+ * learned that lesson already and its docstring says so. Where an
+ * answer holds several anchors, because a reviewer sketched a smaller
+ * array before writing the real one, the richest wins on the same
+ * reasoning as the widest span.
+ */
+export declare function salvageEntries(text: string, key: string): unknown[];
+/**
+ * A non-empty trimmed string, or nothing.
+ *
+ * Absent and blank are the same answer here. A model that sent a field
+ * full of spaces did not fill it in, and holding the spaces would let
+ * an empty subject or a whitespace id through to somewhere that treats
+ * it as a name.
+ */
+export declare function wireText(value: unknown): string | undefined;
+/** A whole number, or nothing. */
+export declare function wireWhole(value: unknown): number | undefined;
+/** A plain object, as against an array or a primitive. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/review/ask/wire.js

@@ -0,0 +1,204 @@
+/**
+ * Reading what a model actually sent.
+ *
+ * A model answers in prose with JSON somewhere inside it, however
+ * firmly it was asked not to, and every round has to cope with the
+ * same handful of shapes. This is shared rather than copied because it
+ * is one concept and not two that merely look alike: if models change
+ * how they wrap an answer, every round is wrong in the same way at the
+ * same time, and there should be one place to fix it.
+ */
+/**
+ * The JSON object in an answer, wherever it is.
+ *
+ * Tries the whole answer, then a fenced block, then the widest
+ * brace-delimited span. Widest rather than first, because a model that
+ * reasons before answering often writes a smaller object earlier in
+ * the prose. The fence is tried before the span because a model
+ * quoting code in its reasoning puts braces in the prose, and the span
+ * then swallows the prose and parses as nothing.
+ */
+export function findJson(text) {
+    const whole = parseObject(text);
+    if (whole !== undefined)
+        return whole;
+    for (const match of text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g)) {
+        const fenced = parseObject(match[1] ?? "");
+        if (fenced !== undefined)
+            return fenced;
+    }
+    const first = text.indexOf("{");
+    const last = text.lastIndexOf("}");
+    if (first === -1 || last <= first)
+        return undefined;
+    return parseObject(text.slice(first, last + 1));
+}
+/**
+ * What a reviewer said, taking the part that survived over nothing.
+ *
+ * Every round reads its answer the same way and can be interrupted in
+ * the same place, so the fallback belongs here rather than four times
+ * over. A caller that must know it is holding half an answer reads
+ * `truncated`, and every caller must, because a partial answer that
+ * does not say so is a reviewer that appears to have found less than
+ * it did.
+ */
+export function readAnswer(text, key) {
+    const whole = findJson(text);
+    if (whole !== undefined)
+        return { parsed: whole, truncated: false };
+    const salvaged = salvageEntries(text, key);
+    return salvaged.length === 0
+        ? { parsed: undefined, truncated: false }
+        : { parsed: { [key]: salvaged }, truncated: true };
+}
+/**
+ * How a round says an answer stopped early.
+ *
+ * Worth wording once. The reader has to come away knowing that the
+ * gap is unmeasured, or a truncated answer gets read as a thorough
+ * one, which is how a round can look complete while missing the
+ * finding that mattered.
+ */
+export const ANSWER_WAS_CUT_OFF = "This answer was cut off partway through, so what follows is what survived: everything the reviewer completed before it stopped, and not the entry it was in the middle of. There is no way to tell how much more it would have sent, so treat an absence here as unknown rather than as nothing to report.";
+/**
+ * What an answer still holds after it was cut off.
+ *
+ * A reviewer stopped at its budget stops wherever it had got to,
+ * which for a long answer is partway through the findings array. The
+ * text will not parse, and dropping it loses every finding that did
+ * arrive whole along with the one that did not.
+ *
+ * Nothing is repaired. Each entry of the named array is taken on its
+ * own and handed to the parser by itself: one that finished parses,
+ * one that did not, does not. An earlier version cut the text at a
+ * point where everything open could be closed and let the closers do
+ * the rest, which is a property of the syntax rather than of the
+ * entries. Every real finding holds a nested location, so an entry
+ * interrupted after that location closed satisfied the rule, and a
+ * half-written finding came back looking exactly like a whole one
+ * with its argument missing. A finding completed by guesswork cannot
+ * be told from one the reviewer made, which is the one outcome worth
+ * refusing outright.
+ *
+ * Anchored on the key rather than the first brace, which is also why
+ * a brace in the reviewer's prose no longer costs the answer: `findJson`
+ * learned that lesson already and its docstring says so. Where an
+ * answer holds several anchors, because a reviewer sketched a smaller
+ * array before writing the real one, the richest wins on the same
+ * reasoning as the widest span.
+ */
+export function salvageEntries(text, key) {
+    let best = [];
+    const anchor = new RegExp(`"${key}"\\s*:\\s*\\[`, "g");
+    for (const found of text.matchAll(anchor)) {
+        const at = (found.index ?? 0) + found[0].length;
+        const entries = entriesFrom(text, at);
+        if (entries.length > best.length)
+            best = entries;
+    }
+    return best;
+}
+/**
+ * The whole entries of an array, reading from just inside its bracket.
+ *
+ * Depth is counted relative to the array, so a boundary means the end
+ * of one of its entries and never the end of something nested inside
+ * one. An entry still open when the text runs out is not an entry.
+ */
+function entriesFrom(text, from) {
+    const entries = [];
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    const take = (end) => {
+        if (start === -1)
+            return;
+        try {
+            entries.push(JSON.parse(text.slice(start, end)));
+        }
+        catch {
+            // Whatever this was, the reviewer did not finish saying it.
+        }
+        start = -1;
+    };
+    for (let at = from; at < text.length; at++) {
+        const char = text[at];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"') {
+            if (start === -1)
+                start = at;
+            inString = true;
+        }
+        else if (char === "{" || char === "[") {
+            if (start === -1)
+                start = at;
+            depth++;
+        }
+        else if (char === "}" || char === "]") {
+            // At depth zero this closes the array itself, or the object
+            // holding it, so the last entry ends here and so does the walk.
+            if (depth === 0) {
+                take(at);
+                break;
+            }
+            depth--;
+        }
+        else if (char === "," && depth === 0) {
+            take(at);
+        }
+        else if (start === -1 && !/\s/.test(char)) {
+            start = at;
+        }
+    }
+    return entries;
+}
+/** One JSON object, or nothing. */
+function parseObject(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return undefined;
+    try {
+        const held = JSON.parse(trimmed);
+        return isRecord(held) ? held : undefined;
+    }
+    catch {
+        // Not JSON. Every caller is guessing at where the JSON might
+        // be, so failing to find it is the expected outcome rather
+        // than an error worth reporting.
+        return undefined;
+    }
+}
+/**
+ * A non-empty trimmed string, or nothing.
+ *
+ * Absent and blank are the same answer here. A model that sent a field
+ * full of spaces did not fill it in, and holding the spaces would let
+ * an empty subject or a whitespace id through to somewhere that treats
+ * it as a name.
+ */
+export function wireText(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** A whole number, or nothing. */
+export function wireWhole(value) {
+    return typeof value === "number" && Number.isInteger(value)
+        ? value
+        : undefined;
+}
+/** A plain object, as against an array or a primitive. */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/review/attach.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Which change a call is about, when the caller did not say.
+ *
+ * Every review tool used to demand a change on every call, so
+ * reading a diff and then its threads meant naming the same
+ * pull request twice, and the second naming was where typos
+ * lived. A session attaches to what it is working on instead,
+ * and a call without a change acts on that.
+ *
+ * The rule is the browser integration's, because it was learned
+ * the same way and there is no reason for two answers to the
+ * same question. What differs is only the vocabulary: sessions
+ * are opened and changes are attached.
+ */
+import type { ChangeRef } from "./change.js";
+/** A change this session is working on. */
+export interface Attachment {
+    readonly change: ChangeRef;
+    /** When it was attached, for the reader rather than for sorting. */
+    readonly attachedAt: string;
+    /**
+     * Position in the order things were attached, climbing.
+     *
+     * A timestamp cannot do this job. Attaching two changes in
+     * quick succession, which is exactly what happens when a
+     * stack is attached, lands them in the same millisecond and
+     * leaves the order down to whatever the filesystem hands
+     * back. A counter is monotonic by construction and survives a
+     * restart, since it is derived from what is already on disk.
+     */
+    readonly seq: number;
+}
+/** Durable home for what a session is attached to. */
+export interface AttachmentStore {
+    /** Attach a change, or freshen one already attached. */
+    attach(change: ChangeRef): Promise<void>;
+    /**
+     * Attach a change beneath everything already here.
+     *
+     * For a fork taking on what the session it came from was working
+     * on. Those attachments happened before this session existed, and
+     * the sequence is what decides which change a call acts on when it
+     * names none, so one inherited from a parent must never outrank
+     * something this session said itself.
+     */
+    inherit(change: ChangeRef): Promise<void>;
+    /** Detach by label, reporting whether there was one to detach. */
+    detach(label: string): Promise<boolean>;
+    /** Newest first. */
+    list(): Promise<Attachment[]>;
+}
+/**
+ * Carry one session's attachments into another.
+ *
+ * For a fork, which is the same work continued under a new session
+ * id. Scoping attachments by session is what stopped one session
+ * retargeting another's round, and it made a fork start with nothing
+ * attached, so the first call after one either refused for want of a
+ * change or acted on whatever was named by hand. Neither is what
+ * forking means.
+ *
+ * A copy rather than a move: the session forked from is still there
+ * and still working on what it was working on.
+ *
+ * Never overwrites a change the fork already holds, and carried ones
+ * are attached oldest first, so the parent's order survives and
+ * anything the fork attaches afterwards outranks all of it. That
+ * ordering is the point rather than a detail: `changeInPlay` takes the
+ * most recent when a call names nothing, so an inherited change
+ * outranking what this session just said it was working on would act
+ * on the wrong one and announce it as the most recent.
+ *
+ * Written through the store's own `attach`, so the record's shape and
+ * the sequence rule stay in one place. Reading through a store and
+ * writing around it is how two spellings of one format come about.
+ *
+ * Awaited at session start, unlike the reclamations it sits beside.
+ * Those are about the machine; this is about the answer to the next
+ * call, and a fork whose first review call lands before the copy
+ * finishes sees the refusal this exists to prevent.
+ *
+ * Advisory in what it reads: what it cannot read it does not carry,
+ * and nothing about a fork fails over it.
+ *
+ * Returns how many were carried.
+ */
+export declare function inheritAttachments(root: string, from: string, to: string): Promise<number>;
+/**
+ * Give back the directories of sessions that have stopped using them.
+ *
+ * Scoping attachments per session means one directory per session for
+ * as long as the state directory lives, so something has to take them
+ * back. Age is judged on the newest attachment inside, not on the
+ * directory itself: a directory's timestamp moves when an entry is
+ * added or removed and stands still when one is rewritten in place, so
+ * a session that keeps freshening the same change would age as though
+ * nobody had touched it. The one asking is never swept regardless,
+ * because a long-lived session attaches its work once and then only
+ * reads it, which is exactly the shape an age rule mistakes for
+ * abandonment.
+ *
+ * Files are left alone. Attachments made before scoping existed sit
+ * flat in the root and belong to no session, so no session's rule
+ * should decide their fate; deleting somebody's attachment to tidy up
+ * is a poor trade for the disk it returns. They cost bytes and are
+ * invisible to every scoped caller.
+ *
+ * Putting them on this clock was tried and taken back out. An orphan
+ * is by definition a file nothing has written since scoping landed, so
+ * judging one by its own age gives no grace to the population it
+ * targets: on any machine where scoping shipped a month ago, every one
+ * of them goes on the first session start after the sweep ships. A
+ * month of grace that protects nobody it was written for is not an
+ * argument, and eighty kilobytes is not a reason to go looking for a
+ * better one.
+ *
+ * An empty directory is swept, since it holds nothing anybody can
+ * lose.
+ *
+ * Returns how many were taken back.
+ */
+export declare function pruneAttachments(root: string, options: {
+    olderThanMs: number;
+    keep?: string;
+}): Promise<number>;
+/**
+ * Attachments on disk, one flat directory of JSON files.
+ *
+ * The same idiom as the draft store, and for the same reasons:
+ * legible to somebody who goes looking, cheap to list, and with
+ * no index that can fall out of step with the files it claims to
+ * describe.
+ */
+export declare function createAttachmentStore(root: string, sessionId: string): AttachmentStore;
+/** The change a call settled on, and why, when it is worth saying. */
+export interface ChangeInPlay {
+    readonly label: string;
+    /** Said out loud when the caller did not name this themselves. */
+    readonly note?: string;
+}
+/** No single answer, so the caller has to choose. */
+export interface ChangeAmbiguous {
+    readonly candidates: readonly string[];
+}
+/**
+ * Which attached change a call should act on.
+ *
+ * An explicit name is never second-guessed: somebody who names a
+ * change means that change, and a typo is better reported than
+ * quietly redirected to whatever else happens to be attached.
+ *
+ * With nothing named, one attached change is used and said out
+ * loud, so the reader knows what was read or written. Several
+ * stay a refusal rather than a guess, because acting on the
+ * wrong change is worse than being asked which one, and the
+ * hint only breaks that tie when it points at something actually
+ * attached.
+ */
+export declare function changeInPlay(asked: string | undefined, hint: string | undefined, attached: readonly string[]): ChangeInPlay | ChangeAmbiguous;
+/** Say what to choose between, when the choice cannot be made here. */
+export declare function chooseChange(candidates: readonly string[]): string;