@jitsusama/agentic-harness.core 0.1.0

package/dist/result/store.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Payloads a tool answered with, kept where they can be asked
+ * about.
+ *
+ * A tool result has two audiences with opposite needs. The model
+ * needs a few hundred bytes it can reason over; the caller who
+ * then asks a precise question needs the whole thing. A store
+ * settles the argument: the answer carries a bounded view and an
+ * opaque handle, and the payload waits on disk until somebody
+ * queries it.
+ *
+ * The store is its directory, not an object. Every family that
+ * answers with a large payload puts it here, and the one tool that
+ * queries them reads it back, and those are different consumers in
+ * the same process holding different instances. So a handle
+ * resolves against the directory rather than against whichever
+ * instance happened to write it. An in-memory index would have
+ * meant a handle cited by one family was unreadable by the query
+ * tool, which is the only thing a handle is for.
+ *
+ * The quota is what makes this safe to leave on everywhere. A long
+ * session answering large questions would otherwise fill a disk
+ * one honest payload at a time, so a put evicts the oldest
+ * payloads until the directory fits again. It counts what is on
+ * disk rather than what this instance remembers writing, for the
+ * same reason handles resolve that way: several instances share
+ * one directory, and a quota each of them enforced privately would
+ * be a quota multiplied by however many there happened to be.
+ *
+ * Payloads are named after their content, so a page read repeated
+ * across several answers costs one file and yields one handle
+ * rather than a fresh megabyte each time.
+ */
+/**
+ * Raised when a handle no longer resolves: never issued, evicted
+ * under quota, or its file has gone.
+ */
+export declare class HandleExpiredError extends Error {
+    constructor(handle: string);
+}
+/** A payload on disk, and how to ask for it again. */
+export interface StoredResult {
+    handle: string;
+    path: string;
+    bytes: number;
+}
+/** A session's stored payloads, addressed by handle. */
+export interface ResultStore {
+    /** Keep a payload and return its handle, path and size. */
+    put(text: string): StoredResult;
+    /** Read a payload back, or throw HandleExpiredError if it is gone. */
+    read(handle: string): string;
+    /** Whether a handle still resolves. */
+    has(handle: string): boolean;
+}
+/**
+ * What this store minted, as opposed to what it will look up.
+ *
+ * Published unanchored as well, because one other place has to
+ * recognize a handle in running text: the layer that cuts an
+ * oversized answer must not cut through one. Written out there by
+ * hand it became the word "handle" followed by anything, which is
+ * also a sentence about handling errors.
+ *
+ * Deciding which files to count against the quota and delete is a
+ * different question from deciding which names are safe to resolve,
+ * and it needs the stricter answer. The directory may hold
+ * somebody else's files, and evicting one of those to make room for
+ * ours would be a quota enforced with other people's data.
+ */
+export declare const MINTED_HANDLE_SHAPE = "result-[0-9a-f]{16}";
+/**
+ * Create a store backed by files under a directory.
+ *
+ * A payload larger than the whole quota is kept anyway, because it
+ * is still the current result and the answer citing it must
+ * resolve. That is the one case where the store knowingly sits
+ * over its limit, and the next put brings it back down.
+ */
+export declare function createResultStore(deps: {
+    dir: string;
+    maxBytes?: number;
+}): ResultStore;

package/dist/result/store.js

@@ -0,0 +1,214 @@
+/**
+ * Payloads a tool answered with, kept where they can be asked
+ * about.
+ *
+ * A tool result has two audiences with opposite needs. The model
+ * needs a few hundred bytes it can reason over; the caller who
+ * then asks a precise question needs the whole thing. A store
+ * settles the argument: the answer carries a bounded view and an
+ * opaque handle, and the payload waits on disk until somebody
+ * queries it.
+ *
+ * The store is its directory, not an object. Every family that
+ * answers with a large payload puts it here, and the one tool that
+ * queries them reads it back, and those are different consumers in
+ * the same process holding different instances. So a handle
+ * resolves against the directory rather than against whichever
+ * instance happened to write it. An in-memory index would have
+ * meant a handle cited by one family was unreadable by the query
+ * tool, which is the only thing a handle is for.
+ *
+ * The quota is what makes this safe to leave on everywhere. A long
+ * session answering large questions would otherwise fill a disk
+ * one honest payload at a time, so a put evicts the oldest
+ * payloads until the directory fits again. It counts what is on
+ * disk rather than what this instance remembers writing, for the
+ * same reason handles resolve that way: several instances share
+ * one directory, and a quota each of them enforced privately would
+ * be a quota multiplied by however many there happened to be.
+ *
+ * Payloads are named after their content, so a page read repeated
+ * across several answers costs one file and yields one handle
+ * rather than a fresh megabyte each time.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spillText } from "./spill.js";
+/**
+ * Raised when a handle no longer resolves: never issued, evicted
+ * under quota, or its file has gone.
+ */
+export class HandleExpiredError extends Error {
+    constructor(handle) {
+        super(`result handle ${handle} is no longer available`);
+        this.name = "HandleExpiredError";
+    }
+}
+/**
+ * The shape a handle must have to be looked up.
+ *
+ * A handle arrives from a language model, which means it can be
+ * anything at all, including a relative path with enough parent
+ * directories in it to leave the store. This is a guard against
+ * that, not a description of what minting happens to produce: it
+ * allows any name built from letters, digits, dash and underscore,
+ * which cannot escape a directory, and refuses everything else.
+ *
+ * It was briefly the exact minted shape, sixteen hex digits with a
+ * prefix, which is a different and worse rule. It rejects a handle
+ * from any other minting scheme, and it made a truncated handle
+ * indistinguishable from a hostile one when what a caller needed to
+ * hear was that their handle had been cut.
+ */
+const HANDLE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/**
+ * What this store minted, as opposed to what it will look up.
+ *
+ * Published unanchored as well, because one other place has to
+ * recognize a handle in running text: the layer that cuts an
+ * oversized answer must not cut through one. Written out there by
+ * hand it became the word "handle" followed by anything, which is
+ * also a sentence about handling errors.
+ *
+ * Deciding which files to count against the quota and delete is a
+ * different question from deciding which names are safe to resolve,
+ * and it needs the stricter answer. The directory may hold
+ * somebody else's files, and evicting one of those to make room for
+ * ours would be a quota enforced with other people's data.
+ */
+export const MINTED_HANDLE_SHAPE = "result-[0-9a-f]{16}";
+const MINTED_PATTERN = new RegExp(`^${MINTED_HANDLE_SHAPE}$`);
+/** The extension every stored payload is written under. */
+const PAYLOAD_EXTENSION = ".json";
+/**
+ * Create a store backed by files under a directory.
+ *
+ * A payload larger than the whole quota is kept anyway, because it
+ * is still the current result and the answer citing it must
+ * resolve. That is the one case where the store knowingly sits
+ * over its limit, and the next put brings it back down.
+ */
+export function createResultStore(deps) {
+    /** Whether a filesystem error means the file simply is not there. */
+    function isMissing(err) {
+        return (typeof err === "object" &&
+            err !== null &&
+            "code" in err &&
+            (err.code === "ENOENT" || err.code === "ENOTDIR"));
+    }
+    function pathFor(handle) {
+        if (!HANDLE_PATTERN.test(handle))
+            return undefined;
+        return path.join(deps.dir, `${handle}${PAYLOAD_EXTENSION}`);
+    }
+    // Re-reads the directory on every put rather than keeping a tally.
+    // That looks wasteful and was raised as such; measured, it is 0.36
+    // ms per put with 50 payloads on disk and 1.37 ms with 500, next
+    // to a put that has just written tens of kilobytes and a tool call
+    // that took hundreds of milliseconds to produce them. A cached
+    // tally would also be wrong rather than slow: the directory is
+    // shared with every other consumer in the session, so anything
+    // remembered between calls is a guess about what somebody else
+    // has written since.
+    //
+    // By name, never by path: a spill reports the directory's real
+    // path, the caller may have given us a symlinked one, and on macOS
+    // those differ for anything under the temp directory. Comparing
+    // paths there quietly evicted the payload we had just written and
+    // were about to cite.
+    function evictWhileOver(keepName) {
+        if (deps.maxBytes === undefined)
+            return;
+        let held = payloadsOnDisk(deps.dir);
+        let total = held.reduce((sum, entry) => sum + entry.bytes, 0);
+        // Oldest first, so what goes is what has had the longest
+        // chance to be queried already.
+        held = held.sort((a, b) => a.modifiedMs - b.modifiedMs);
+        for (const entry of held) {
+            if (total <= deps.maxBytes)
+                break;
+            if (path.basename(entry.path) === keepName)
+                continue;
+            try {
+                fs.rmSync(entry.path, { force: true });
+                total -= entry.bytes;
+            }
+            catch {
+                // A file that will not delete still occupies disk, so its
+                // bytes stay counted rather than the store claiming space it
+                // did not reclaim.
+            }
+        }
+    }
+    return {
+        put(text) {
+            const written = spillText(text, deps.dir);
+            const bytes = Buffer.byteLength(text, "utf-8");
+            evictWhileOver(path.basename(written.path));
+            return {
+                handle: handleFor(written.path),
+                path: written.path,
+                bytes,
+            };
+        },
+        read(handle) {
+            const file = pathFor(handle);
+            if (!file)
+                throw new HandleExpiredError(handle);
+            try {
+                return fs.readFileSync(file, "utf-8");
+            }
+            catch (err) {
+                // Only a missing file is an expiry. Reporting a permission
+                // error or a full disk as "this handle is no longer
+                // available" sends the caller off to re-run the work that
+                // produced it, which will fail the same way, and hides the
+                // one detail that would have explained why.
+                if (isMissing(err))
+                    throw new HandleExpiredError(handle);
+                throw new Error(`Handle ${handle} is on disk but could not be read: ` +
+                    `${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+        },
+        has(handle) {
+            const file = pathFor(handle);
+            return file !== undefined && fs.existsSync(file);
+        },
+    };
+}
+/** Every payload currently in a store's directory, with its age and size. */
+function payloadsOnDisk(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        // No directory yet means no payloads, which is not an error: the
+        // first put is what creates it.
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        if (!name.endsWith(PAYLOAD_EXTENSION))
+            continue;
+        if (!MINTED_PATTERN.test(name.slice(0, -PAYLOAD_EXTENSION.length)))
+            continue;
+        const full = path.join(dir, name);
+        try {
+            const stat = fs.statSync(full);
+            if (!stat.isFile())
+                continue;
+            found.push({ path: full, bytes: stat.size, modifiedMs: stat.mtimeMs });
+        }
+        catch {
+            // It vanished between the listing and the stat, so it is not
+            // holding any disk and does not belong in the tally.
+        }
+    }
+    return found;
+}
+/** Derive a handle from a spilled file's path. */
+function handleFor(filePath) {
+    const base = filePath.split(/[\\/]/).pop() ?? filePath;
+    return base.replace(/\.[^.]+$/, "");
+}

package/dist/result/view.d.ts

@@ -0,0 +1,31 @@
+/**
+ * As much of a rendered view as a budget affords.
+ *
+ * Whole lines only. Half a line is not a smaller truth, it is a
+ * wrong one: a caller who reads "butto" has been handed a node
+ * that does not exist, and a request row cut mid-url points at
+ * somewhere nobody asked for.
+ *
+ * Never none, either. An answer that cut everything tells the
+ * caller nothing about where they are, so a single line over
+ * budget is still returned. The budget is a presentation default,
+ * and the payload it cut is stored rather than lost.
+ *
+ * This knows nothing about what it is cutting. What to do about a
+ * cut view differs by family, since narrowing a page read and
+ * narrowing a request listing use different words, so the advice
+ * belongs to whoever knows those words.
+ */
+/** A view cut to fit, and what fitting it cost. */
+export interface BudgetedView {
+    /** The view, whole lines only. */
+    readonly text: string;
+    /** Lines the render produced. */
+    readonly total: number;
+    /** Lines this view carries. */
+    readonly shown: number;
+    /** Lines cut, which is zero when it all fit. */
+    readonly cut: number;
+}
+/** Keep the leading whole lines of a view that fit a byte budget. */
+export declare function withinLineBudget(rendered: string, budget: number): BudgetedView;

package/dist/result/view.js

@@ -0,0 +1,38 @@
+/**
+ * As much of a rendered view as a budget affords.
+ *
+ * Whole lines only. Half a line is not a smaller truth, it is a
+ * wrong one: a caller who reads "butto" has been handed a node
+ * that does not exist, and a request row cut mid-url points at
+ * somewhere nobody asked for.
+ *
+ * Never none, either. An answer that cut everything tells the
+ * caller nothing about where they are, so a single line over
+ * budget is still returned. The budget is a presentation default,
+ * and the payload it cut is stored rather than lost.
+ *
+ * This knows nothing about what it is cutting. What to do about a
+ * cut view differs by family, since narrowing a page read and
+ * narrowing a request listing use different words, so the advice
+ * belongs to whoever knows those words.
+ */
+/** Keep the leading whole lines of a view that fit a byte budget. */
+export function withinLineBudget(rendered, budget) {
+    const lines = rendered.length === 0 ? [] : rendered.split("\n");
+    const kept = [];
+    let spent = 0;
+    for (const line of lines) {
+        // The newline this line costs once it is joined back up.
+        const cost = Buffer.byteLength(line, "utf-8") + 1;
+        if (kept.length > 0 && spent + cost > budget)
+            break;
+        kept.push(line);
+        spent += cost;
+    }
+    return {
+        text: kept.join("\n"),
+        total: lines.length,
+        shown: kept.length,
+        cut: lines.length - kept.length,
+    };
+}

package/dist/review/anchor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Where a remark attaches to a change.
+ *
+ * The shape is git's: a path, a side (the file before or the
+ * file after), a line or line range, and the commit the
+ * anchor was formed against. That last field is what makes
+ * an anchor honest across a force-push. One backend keeps
+ * the witness commit reachable and has no notion of a stale
+ * comment; another strands the thread and reports it as
+ * outdated. Recording the witness lets the substrate say
+ * which of those happened instead of guessing.
+ */
+import type { DiffFile, DiffHunk, DiffModel, DiffSide } from "./diff.js";
+export type { DiffSide };
+/** A remark about one line or a run of lines. */
+export interface LineAnchor {
+    subject: "line";
+    path: string;
+    blob: DiffSide;
+    /** Last line of the range, or the only line. */
+    line: number;
+    /** First line of a multi-line range. */
+    startLine?: number;
+    /** Commit the anchor was formed against. */
+    witness?: string;
+}
+/** A remark about a file as a whole. */
+export interface FileAnchor {
+    subject: "file";
+    path: string;
+    /** Side the path is named on. Defaults to the new side. */
+    blob?: DiffSide;
+    witness?: string;
+}
+/**
+ * A remark about the change as a whole.
+ *
+ * Its shape, its scope, the commit it sits on, whether it should
+ * be one change or three: things a reviewer says about the work
+ * rather than about a line of it. There is no place in a diff for
+ * one, which is the point. Naming it lets a backend that has
+ * somewhere to put it do so, and lets the rest spill it into the
+ * review body knowing why.
+ */
+export interface ChangeAnchor {
+    subject: "change";
+    witness?: string;
+}
+/** Where a remark attaches. */
+export type Anchor = LineAnchor | FileAnchor | ChangeAnchor;
+/** Why an anchor cannot land on a diff. */
+export type AnchorRefusal = "file-absent" | "line-absent" | "range-inverted" | "range-crosses-hunks"
+/** The remark named no place, so there is none to find. */
+ | "not-a-place";
+/** Whether an anchor lands, and what it landed on. */
+export type AnchorCheck = {
+    anchored: true;
+    file: DiffFile;
+    hunk?: DiffHunk;
+} | {
+    anchored: false;
+    reason: AnchorRefusal;
+};
+/** The path an anchor names, when it names one. */
+export declare function anchorPath(anchor: Anchor): string | undefined;
+/**
+ * Where a remark points, in a form a person can scan.
+ *
+ * One spelling, because an anchor read four different ways in
+ * four views is four chances to describe the same place
+ * differently.
+ */
+export declare function describeAnchor(anchor: Anchor): string;
+/**
+ * Decide whether an anchor can land on a diff.
+ *
+ * A line anchor lands when the diff shows that line on the
+ * side the anchor names: an added line exists only on the
+ * new side, a removed line only on the old side, and a
+ * context line on both. A range must sit inside one hunk,
+ * because a remark spanning a gap in the diff has no
+ * meaning to a reader and no backend accepts one.
+ */
+export declare function anchorable(diff: DiffModel, anchor: Anchor): AnchorCheck;

package/dist/review/anchor.js

@@ -0,0 +1,89 @@
+/**
+ * Where a remark attaches to a change.
+ *
+ * The shape is git's: a path, a side (the file before or the
+ * file after), a line or line range, and the commit the
+ * anchor was formed against. That last field is what makes
+ * an anchor honest across a force-push. One backend keeps
+ * the witness commit reachable and has no notion of a stale
+ * comment; another strands the thread and reports it as
+ * outdated. Recording the witness lets the substrate say
+ * which of those happened instead of guessing.
+ */
+/** The path an anchor names, when it names one. */
+export function anchorPath(anchor) {
+    return anchor.subject === "change" ? undefined : anchor.path;
+}
+/**
+ * Where a remark points, in a form a person can scan.
+ *
+ * One spelling, because an anchor read four different ways in
+ * four views is four chances to describe the same place
+ * differently.
+ */
+export function describeAnchor(anchor) {
+    if (anchor.subject === "change")
+        return "the change as a whole";
+    if (anchor.subject === "file")
+        return anchor.path;
+    const lines = anchor.startLine && anchor.startLine !== anchor.line
+        ? `${anchor.startLine}-${anchor.line}`
+        : `${anchor.line}`;
+    return `${anchor.path}:${lines}`;
+}
+/** The side an anchor names, defaulting to the new side. */
+function sideOf(anchor) {
+    return anchor.blob ?? "new";
+}
+/** The path a file carries on one side of the diff. */
+function pathOn(file, side) {
+    return side === "old" ? file.oldPath : file.newPath;
+}
+/** Whether a hunk line exists on the given side. */
+function lineOn(hunk, side, line) {
+    return hunk.lines.some((entry) => side === "old" ? entry.oldLine === line : entry.newLine === line);
+}
+/** The hunk holding a line on the given side, if any. */
+function hunkHolding(file, side, line) {
+    return file.hunks.find((hunk) => lineOn(hunk, side, line));
+}
+/**
+ * Decide whether an anchor can land on a diff.
+ *
+ * A line anchor lands when the diff shows that line on the
+ * side the anchor names: an added line exists only on the
+ * new side, a removed line only on the old side, and a
+ * context line on both. A range must sit inside one hunk,
+ * because a remark spanning a gap in the diff has no
+ * meaning to a reader and no backend accepts one.
+ */
+export function anchorable(diff, anchor) {
+    // Asked of a remark that named no place, the honest answer is
+    // that there was nothing to look for. Falling through to the
+    // path lookup would blame a file the remark never mentioned.
+    if (anchor.subject === "change") {
+        return { anchored: false, reason: "not-a-place" };
+    }
+    const side = sideOf(anchor);
+    const file = diff.files.find((entry) => pathOn(entry, side) === anchor.path);
+    if (!file)
+        return { anchored: false, reason: "file-absent" };
+    if (anchor.subject === "file")
+        return { anchored: true, file };
+    const start = anchor.startLine ?? anchor.line;
+    if (start > anchor.line) {
+        return { anchored: false, reason: "range-inverted" };
+    }
+    const hunk = hunkHolding(file, side, start);
+    if (!hunk)
+        return { anchored: false, reason: "line-absent" };
+    if (!lineOn(hunk, side, anchor.line)) {
+        // The end line may be absent outright, or present in a
+        // later hunk; those are different refusals.
+        const reason = hunkHolding(file, side, anchor.line)
+            ? "range-crosses-hunks"
+            : "line-absent";
+        return { anchored: false, reason };
+    }
+    return { anchored: true, file, hunk };
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Agents another harness already defined in the repo under review.
+ *
+ * A repo that has been worked in for a while has usually accumulated
+ * some: a reviewer, an architect, a debugger, each written by somebody
+ * who knew that codebase. They are lenses, which is what a persona is,
+ * and they are already there, which is more than can be said for any
+ * lens this tool ships. Offering them costs a directory read.
+ *
+ * Three rules make that safe, and the third is the one that matters.
+ *
+ * They are namespaced, because a roster naming a lens and silently
+ * getting the repo's version of it is the quiet substitution
+ * `bindPersonas` refuses: the findings still file under the name, and
+ * whoever reads them weighs them as the lens they asked for.
+ *
+ * Only the prose comes across. Measured across fifteen agent files on
+ * this machine, thirteen name tools and six name a model, in
+ * vocabulary that belongs to the harness that wrote them: `sonnet` is
+ * not a model pi resolves and `Bash, Read, Edit` are not tools it has.
+ *
+ * And the change under review may not be the thing that wrote them. A
+ * charter becomes the reviewer's `--system-prompt`, on a child holding
+ * bash and write, with its working directory inside the tree, and that
+ * tree is pinned to the commit under review. So without this rule the
+ * author of a change writes the standing instruction of the agent
+ * reviewing it, and the operator's consent is worth little, since the
+ * listing they chose from read a different tree. A lens the diff
+ * touches is refused. What remains is the repo's committed state,
+ * which is the same trust already extended to every other line in it.
+ *
+ * Reading the directory is somebody else's job, as it is for personas.
+ * This module is handed the files.
+ */
+/** A file that might describe an agent. */
+export interface AgentFile {
+    /** Where it was found, relative to the repo, for reporting. */
+    path: string;
+    /**
+     * Where the bytes actually came from, when that is somewhere else.
+     *
+     * A symlink inside the tree is followed for its content and was
+     * checked against the diff by the link's own path, so a change could
+     * edit the file the link points at and leave the link untouched.
+     */
+    reads?: string;
+    text: string;
+}
+/** A lens the repo under review already had. */
+export interface RepoAgent {
+    /** Namespaced id, which is how a roster asks for it. */
+    id: string;
+    name: string;
+    description: string;
+    /** The charter prose: the file body, frontmatter stripped. */
+    charter: string;
+    source: string;
+    /** Frontmatter fields deliberately left behind, if any. */
+    notAdopted?: string[];
+}
+/** What a directory of agent files yielded, and what it did not. */
+export interface AgentDiscovery {
+    agents: RepoAgent[];
+    skipped: {
+        path: string;
+        why: string;
+    }[];
+}
+/** The prefix that keeps these out of the persona namespace. */
+export declare const NAMESPACE = "repo:";
+/**
+ * Read what a repo's agent files offer.
+ *
+ * Lenient where the persona reader is strict, and the difference is
+ * who asked. A persona is named in somebody's own config, so a
+ * malformed one is a mistake they want reported loudly. Nobody asked
+ * for these, so one malformed file in a repo this operator does not
+ * maintain must not refuse every round run against it.
+ */
+export declare function discoverAgents(files: AgentFile[], touched: readonly string[]): AgentDiscovery;