@jitsusama/agentic-harness.core 0.1.0

package/dist/work/ask.js

@@ -0,0 +1,85 @@
+/**
+ * Turning a loose ask into a tree request, or a sentence saying
+ * why not.
+ *
+ * The broker takes a `TreeRequest` whose two shapes need
+ * different fields, and a tool surface takes whatever the caller
+ * sent. Somewhere in between, a caller who sent a commit where a
+ * branch belonged has to be told that specifically, rather than
+ * being handed a generic complaint or, worse, having the provider
+ * fail somewhere further from the cause.
+ *
+ * This is where. It is pure, so the refusals can be read as a set
+ * rather than discovered one live call at a time.
+ */
+/** Build a tree request, or refuse with the missing part named. */
+export function treeRequestFrom(ask) {
+    const purpose = ask.purpose?.trim();
+    if (!purpose) {
+        return {
+            refusal: "Say what the tree is for: the purpose names it, so without " +
+                "one there is nothing to call it or to recognise it by later.",
+        };
+    }
+    // Where a tree can be cut from is deliberately not asked here.
+    // It reads like the same kind of question as the rest, and it is
+    // not: the others are about whether the caller's own words hang
+    // together, which is knowable from the words. This one is about
+    // the world, and the answer belongs to whichever provider is
+    // about to be chosen.
+    //
+    // Answering it here answered it for the git provider, which does
+    // need a checkout or a remote, and imposed that on every other
+    // provider before one was picked. A provider needing neither
+    // could not be reached at all: `dev tree` knows where World
+    // lives, so a World snapshot could only be cut by naming a
+    // checkout the provider then ignored, and a World review round
+    // with nothing configured degraded to reading the caller's own
+    // tree while the right tree sat there waiting to be used.
+    //
+    // The git provider refuses it for itself, closer to the cause
+    // and with more to say: nothing known at all is a different
+    // answer from known only as a remote it will not clone unasked.
+    if (ask.intent === "worktree") {
+        if (!ask.branch) {
+            // Having been sent a commit is a different mistake from
+            // having sent nothing, and worth separating: one caller
+            // forgot a field, the other chose the wrong one.
+            const instead = ask.commit
+                ? ` A commit (${ask.commit}) was given instead; a worktree ` +
+                    "is checked out at a branch, so ask for a snapshot if you " +
+                    "meant to pin that commit."
+                : "";
+            return {
+                refusal: `A worktree needs a branch to check out.${instead}`,
+            };
+        }
+        return {
+            request: {
+                intent: "worktree",
+                repo: ask.repo,
+                purpose,
+                branch: ask.branch,
+            },
+        };
+    }
+    if (!ask.commit) {
+        const instead = ask.branch
+            ? ` A branch (${ask.branch}) was given instead; a snapshot is ` +
+                "pinned to one commit, so ask for a worktree if you meant to " +
+                "work on that branch."
+            : "";
+        return {
+            refusal: `A snapshot needs a commit to pin.${instead}`,
+        };
+    }
+    return {
+        request: {
+            intent: "snapshot",
+            repo: ask.repo,
+            purpose,
+            commit: ask.commit,
+            ...(ask.paths ? { paths: ask.paths } : {}),
+        },
+    };
+}

package/dist/work/author.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Recording work: staging, committing, and moving onto a branch.
+ *
+ * The history facet reads a tree and this one writes to it, kept
+ * apart because reading is safe and writing is not. A consumer
+ * that only wants to know whether a tree is dirty should not be
+ * handed the ability to commit in it.
+ *
+ * Names are checked here rather than left to git, and not only for
+ * the names git would reject anyway. The dangerous ones are the
+ * names git accepts: a branch called `-rf` is a valid ref and a
+ * flag to every command that later takes it, so it has to be
+ * refused before it reaches a command line rather than after.
+ */
+import { type Exec } from "../exec/index.js";
+/** What a commit says. */
+export interface CommitMessage {
+    subject: string;
+    body?: string;
+}
+/** Where a new branch starts. */
+export interface BranchOptions {
+    from?: string;
+}
+/** Writing to a tree. */
+export interface WorkAuthor {
+    /** Stage these paths, or everything when none are named. */
+    stage(treePath: string, paths?: readonly string[]): Promise<void>;
+    /** Record what is staged. */
+    commit(treePath: string, message: CommitMessage): Promise<void>;
+    /** Create a branch and check it out. */
+    branch(treePath: string, name: string, options?: BranchOptions): Promise<void>;
+}
+/**
+ * A ref name, trimmed, or nothing when it is not safe to use.
+ *
+ * Returns the name rather than a boolean so a caller cannot check
+ * one string and then pass a different one, which is the shape of
+ * mistake that makes a validator decorative.
+ */
+export declare function safeBranchName(name: string): string | undefined;
+/**
+ * Where a branch name departs from the house convention.
+ *
+ * Advice, not a verdict. {@link safeBranchName} decides what git will
+ * accept and this decides what the convention prefers, and the two
+ * must not be confused: a name git accepts is workable, and a repo
+ * with its own conventions is entitled to it. So this decorates the
+ * answer rather than blocking the branch, which is the same shape as
+ * every other caution here.
+ *
+ * The `username/` prefix is checked for shape and not for identity.
+ * Who the authenticated user is belongs to whatever hosts the repo,
+ * and this layer speaks git; asking a forge would put a network call
+ * behind making a branch.
+ */
+export declare function namingComplaints(name: string): string[];
+/** Write to a tree with plain git. */
+export declare function createGitAuthor(deps: {
+    exec: Exec;
+}): WorkAuthor;

package/dist/work/author.js

@@ -0,0 +1,144 @@
+/**
+ * Recording work: staging, committing, and moving onto a branch.
+ *
+ * The history facet reads a tree and this one writes to it, kept
+ * apart because reading is safe and writing is not. A consumer
+ * that only wants to know whether a tree is dirty should not be
+ * handed the ability to commit in it.
+ *
+ * Names are checked here rather than left to git, and not only for
+ * the names git would reject anyway. The dangerous ones are the
+ * names git accepts: a branch called `-rf` is a valid ref and a
+ * flag to every command that later takes it, so it has to be
+ * refused before it reaches a command line rather than after.
+ */
+import { run } from "../exec/index.js";
+// The leaf rather than the barrel, so a working layer that never draws anything
+// does not pull the TUI in behind one string helper.
+import { displayPath } from "../ui/path.js";
+/**
+ * Characters and shapes a ref may not carry.
+ *
+ * This is git's own `check-ref-format` rule set, minus the parts
+ * that need a repo to answer, plus the leading dash. Doing it as a
+ * deny list rather than an allow list is deliberate: branch names
+ * legitimately carry slashes, dots and unicode, and an allow list
+ * narrow enough to be safe would refuse names people already use.
+ */
+const UNSAFE_IN_REF = /[\s~^:?*[\\]|\.\.|^-|^\/|\/$|\.lock$|^$/;
+/**
+ * Highest code point that is a control character, plus delete.
+ *
+ * Tested by code point rather than folded into the pattern above,
+ * because a regex holding literal control characters is
+ * unreadable and reads to a linter as a mistake. The intent is the
+ * same and the check is easier to be sure of.
+ */
+function hasControlCharacter(name) {
+    for (const character of name) {
+        const code = character.codePointAt(0);
+        if (code === undefined)
+            continue;
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * A ref name, trimmed, or nothing when it is not safe to use.
+ *
+ * Returns the name rather than a boolean so a caller cannot check
+ * one string and then pass a different one, which is the shape of
+ * mistake that makes a validator decorative.
+ */
+export function safeBranchName(name) {
+    const trimmed = name?.trim() ?? "";
+    if (trimmed === "")
+        return undefined;
+    if (hasControlCharacter(trimmed))
+        return undefined;
+    if (UNSAFE_IN_REF.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+/** How long a whole branch name should stay under, by convention. */
+const BRANCH_NAME_BUDGET = 40;
+/**
+ * Where a branch name departs from the house convention.
+ *
+ * Advice, not a verdict. {@link safeBranchName} decides what git will
+ * accept and this decides what the convention prefers, and the two
+ * must not be confused: a name git accepts is workable, and a repo
+ * with its own conventions is entitled to it. So this decorates the
+ * answer rather than blocking the branch, which is the same shape as
+ * every other caution here.
+ *
+ * The `username/` prefix is checked for shape and not for identity.
+ * Who the authenticated user is belongs to whatever hosts the repo,
+ * and this layer speaks git; asking a forge would put a network call
+ * behind making a branch.
+ */
+export function namingComplaints(name) {
+    const said = [];
+    if (!name.includes("/")) {
+        said.push("it has no username prefix, and the form is username/what-it-does");
+    }
+    if (name.length > BRANCH_NAME_BUDGET) {
+        said.push(`it is ${name.length} characters and the convention keeps them under ${BRANCH_NAME_BUDGET}`);
+    }
+    if (name !== name.toLowerCase()) {
+        said.push("it has capitals, and these are lower case with hyphens");
+    }
+    if (name.includes("_")) {
+        said.push("it separates words with underscores rather than hyphens");
+    }
+    return said;
+}
+/** Write to a tree with plain git. */
+export function createGitAuthor(deps) {
+    return {
+        async stage(treePath, paths) {
+            // A bare `git add` stages nothing and reports success, so
+            // everything has to be asked for by name.
+            const args = paths && paths.length > 0 ? ["add", "--", ...paths] : ["add", "--all"];
+            await run(deps.exec, "git", ["-C", treePath, ...args], `Staging work in ${displayPath(treePath)}`);
+        },
+        async commit(treePath, message) {
+            const subject = message.subject?.trim() ?? "";
+            if (subject === "") {
+                throw new Error("A commit needs a subject: it is the line everybody reads " +
+                    "when deciding whether to read the rest.");
+            }
+            const body = message.body?.trim();
+            await run(deps.exec, "git", [
+                "-C",
+                treePath,
+                "commit",
+                "-m",
+                subject,
+                // Git knows how a body is separated from a subject.
+                // Splicing a blank line in by hand is how that gets
+                // done differently in two places.
+                ...(body ? ["-m", body] : []),
+            ], `Recording work in ${displayPath(treePath)}`);
+        },
+        async branch(treePath, name, options) {
+            const safe = safeBranchName(name);
+            if (!safe) {
+                throw new Error(`Not a usable branch name: ${JSON.stringify(name)}. Names ` +
+                    "carrying spaces, a leading dash, or git's reserved " +
+                    "shapes are refused rather than corrected, since " +
+                    "quietly renaming somebody's branch is worse than " +
+                    "declining to make it.");
+            }
+            let from;
+            if (options?.from !== undefined) {
+                from = safeBranchName(options.from);
+                if (!from) {
+                    throw new Error(`Not a usable start point: ${JSON.stringify(options.from)}.`);
+                }
+            }
+            await run(deps.exec, "git", ["-C", treePath, "checkout", "-b", safe, ...(from ? [from] : [])], `Making ${safe} in ${displayPath(treePath)}`);
+        },
+    };
+}

package/dist/work/broker.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Handing out trees and taking them back.
+ *
+ * The broker is the piece that made three tree contracts look like
+ * three problems. Each one held its own trees, keyed them its own
+ * way, and reimplemented the same two questions: does one of these
+ * already answer the request, and who serves this repo. Both
+ * questions now have one answer each, in `tree.ts` and
+ * `provider.ts`, so what is left here is genuinely just custody.
+ */
+import type { Owner } from "../process/index.js";
+import type { TreeMemory } from "./memory.js";
+import { type TreeProviderInfo } from "./provider.js";
+import { type TreeIdentity, type TreeRequest } from "./tree.js";
+/** A tree the broker is holding on somebody's behalf. */
+export interface HeldTree {
+    /** What this tree is, which is what makes it reusable. */
+    identity: TreeIdentity;
+    /** Absolute path to the working directory. */
+    path: string;
+    /**
+     * Who cut it. Recorded because the chosen provider can change
+     * between cutting and releasing, since registration is
+     * dynamic, and a tree has to go back to whoever made it.
+     */
+    providerId: string;
+    /**
+     * The sessions holding it, which is a list because a snapshot is
+     * shareable and two of them can want the same commit at once.
+     *
+     * One field would mean the second session to take a shared tree
+     * erased the first, and the first is still working in it: a single
+     * owner is only correct for a tree nobody may share, and the
+     * shareable kind is the kind this leaks most of.
+     *
+     * Optional because a record written before this existed has none,
+     * and because a machine that will not report a start time gives
+     * half an identity, which is worse than none: a pid alone reads as
+     * whoever holds that number next. Absent means "nobody can say",
+     * which every reader here treats as still held.
+     */
+    owners?: Owner[];
+}
+/** Something that can cut a tree and take it back. */
+export interface TreeProvider extends TreeProviderInfo {
+    /**
+     * Cut a tree for this request. The broker has already decided
+     * that no held tree answers it, so a provider does not need to
+     * dedupe.
+     */
+    ensure(request: TreeRequest): Promise<{
+        path: string;
+    }>;
+    /**
+     * Give up whatever backs this tree. Providers decide whether
+     * that means deleting it, leaving it, or nothing at all.
+     */
+    release(held: HeldTree): Promise<void>;
+}
+/**
+ * What became of a release.
+ *
+ * A discriminated answer rather than nothing, because the interesting case is
+ * the one that used to be silent: no provider registered under the id the tree
+ * was cut by, so there is nothing to remove it through. That used to drop the
+ * record and return, and the tool said "Released" about a directory still on
+ * disk and still tracked by git, now with no record pointing at it. Reporting
+ * success for doing nothing is the one outcome nobody can detect.
+ */
+export type ReleaseOutcome = {
+    kind: "released";
+    /**
+     * How many other sessions are still standing in it, when the
+     * directory was therefore left where it is.
+     *
+     * Absent means it was taken down. A caller that tells somebody
+     * the tree is gone would otherwise be wrong for a shared
+     * snapshot, which is the kind two sessions hold at once.
+     */
+    kept?: number;
+}
+/** Nothing here can remove it, so it is still there and still recorded. */
+ | {
+    kind: "no-provider";
+    /** Who cut it, which is who is missing. */
+    wanted: string;
+    /** Who is registered, so a mismatch reads as a correction. */
+    registered: readonly string[];
+    path: string;
+};
+/** Custody of the trees a session is using. */
+export interface TreeBroker {
+    /** Get a tree for this request, reusing one where possible. */
+    ensure(request: TreeRequest): Promise<HeldTree>;
+    /** Hand a tree back to the provider that cut it, and say what happened. */
+    release(held: HeldTree): Promise<ReleaseOutcome>;
+    /**
+     * Every tree held, this session's first and then any left behind by an
+     * earlier one.
+     *
+     * A tree outlives the process that cut it, so "held" cannot mean "cut by
+     * me". It used to, and the result was every verb refusing on a tree that
+     * plainly existed, with commits inside it and no way back to them.
+     */
+    held(): readonly HeldTree[];
+    /**
+     * Those a running session would miss, which is a narrower set.
+     *
+     * `held` answers what is reachable, and that has to include a dead
+     * session's trees: finding them is the whole reason the record
+     * exists. This answers what is claimed, which is the only question
+     * worth asking before taking a directory away, and the two were
+     * the same set for as long as nothing recorded who cut anything.
+     * Every tree ever cut therefore read as claimed, so nothing was
+     * ever reclaimable: 59 records and 649MB on the machine where
+     * this was found.
+     */
+    stillHeld(): Promise<readonly HeldTree[]>;
+    /** Those held only because nothing recorded who cut them. */
+    unattributed(): readonly HeldTree[];
+    /** Whether this session is the one that cut a tree, for a listing to say so. */
+    cutHere(path: string): boolean;
+}
+/** What a broker needs beyond its providers. */
+export interface BrokerDeps {
+    providers: readonly TreeProvider[] | (() => readonly TreeProvider[]);
+    /**
+     * Where to write down what was cut, so the next session can find it.
+     *
+     * Optional because a caller with no interest in outliving itself, which
+     * means every test, should not have to supply a directory to get a broker.
+     */
+    memory?: TreeMemory;
+}
+/**
+ * Hold the trees a session is using.
+ *
+ * Refuses rather than guessing when the provider choice is not
+ * clear. Cutting a tree from a provider nobody chose is the failure
+ * this is built to avoid: it succeeds, so nothing draws attention
+ * to it, and the tree is merely wrong rather than missing.
+ *
+ * The roster may be a function rather than an array, and usually
+ * should be. Providers arrive over the bus from other packages, and
+ * load order between extensions is not something either one
+ * chooses, so a broker that snapshotted its roster at construction
+ * would be permanently blind to whichever provider happened to load
+ * second. An array stays accepted for a caller that genuinely has a
+ * fixed set, such as a test.
+ */
+export declare function createTreeBroker(said: readonly TreeProvider[] | (() => readonly TreeProvider[]) | BrokerDeps): TreeBroker;

package/dist/work/broker.js

@@ -0,0 +1,165 @@
+/**
+ * Handing out trees and taking them back.
+ *
+ * The broker is the piece that made three tree contracts look like
+ * three problems. Each one held its own trees, keyed them its own
+ * way, and reimplemented the same two questions: does one of these
+ * already answer the request, and who serves this repo. Both
+ * questions now have one answer each, in `tree.ts` and
+ * `provider.ts`, so what is left here is genuinely just custody.
+ */
+import { chooseTreeProvider } from "./provider.js";
+import { satisfies, treeIdentity, } from "./tree.js";
+/**
+ * Hold the trees a session is using.
+ *
+ * Refuses rather than guessing when the provider choice is not
+ * clear. Cutting a tree from a provider nobody chose is the failure
+ * this is built to avoid: it succeeds, so nothing draws attention
+ * to it, and the tree is merely wrong rather than missing.
+ *
+ * The roster may be a function rather than an array, and usually
+ * should be. Providers arrive over the bus from other packages, and
+ * load order between extensions is not something either one
+ * chooses, so a broker that snapshotted its roster at construction
+ * would be permanently blind to whichever provider happened to load
+ * second. An array stays accepted for a caller that genuinely has a
+ * fixed set, such as a test.
+ */
+export function createTreeBroker(said) {
+    const deps = Array.isArray(said) || typeof said === "function"
+        ? { providers: said }
+        : said;
+    const { providers, memory } = deps;
+    const trees = [];
+    const roster = () => typeof providers === "function" ? providers() : providers;
+    /**
+     * This session's trees, then remembered ones it does not already hold.
+     *
+     * Ordered that way deliberately: a tree cut here is the one the caller just
+     * asked about, and deduping by path keeps a remembered copy of it from
+     * appearing twice under two names for the same directory.
+     */
+    const everything = () => {
+        const mine = new Set(trees.map((tree) => tree.path));
+        const earlier = (memory?.recall() ?? []).filter((tree) => !mine.has(tree.path));
+        return [...trees, ...earlier];
+    };
+    return {
+        unattributed() {
+            // Never this session's. Ours were stamped as they were cut, so
+            // anything unattributable came from a record on disk.
+            const mine = new Set(trees.map((tree) => tree.path));
+            return (memory?.unattributed() ?? []).filter((tree) => !mine.has(tree.path));
+        },
+        async stillHeld() {
+            const mine = new Set(trees.map((tree) => tree.path));
+            // Ours are held by definition, whatever a record says: this
+            // process is running, since it is the one asking.
+            const earlier = (await memory?.heldNow())?.filter((tree) => !mine.has(tree.path));
+            return [...trees, ...(earlier ?? [])];
+        },
+        async ensure(request) {
+            // Searches remembered trees too, so a second session reuses what the
+            // first cut instead of cutting a second tree for the same thing.
+            //
+            // A record is not the directory, which is this module's own rule
+            // and was broken here. Returning on a record alone meant the
+            // provider was never asked about any tree already written down,
+            // so a tree standing somewhere other than where it was asked to
+            // stand stayed there for good: a World snapshot left on main by
+            // an older version of its provider could never be pinned,
+            // because the code that pins it was unreachable for exactly the
+            // trees that needed it. The provider is asked either way, and
+            // every provider treats already-there as the ordinary case,
+            // which is what makes `ensure` mean what the word says.
+            const reusable = everything().find((tree) => satisfies(tree.identity, request));
+            if (reusable) {
+                const by = roster().find((provider) => provider.id === reusable.providerId);
+                // Nothing to ask when whoever cut it is not loaded. The
+                // directory is still there and still the right one to hand
+                // back; only the check goes missing, which is where this
+                // stood for every tree until now.
+                if (by !== undefined)
+                    await by.ensure(request);
+                // Taking a tree is holding it, however it was obtained. A
+                // reused tree still carries whoever cut it, and that session
+                // is usually gone: without this, the tree this session is
+                // working in reads as nobody's, and reclaiming it is exactly
+                // the thing that must never happen. Held locally as well,
+                // since our own list is what makes this session's answer true
+                // whatever the record on disk says.
+                if (!trees.some((tree) => tree.path === reusable.path)) {
+                    trees.push(reusable);
+                }
+                await memory?.rememberHeldByUs(reusable);
+                return reusable;
+            }
+            const choice = chooseTreeProvider(roster(), request.repo);
+            if (choice.kind === "none") {
+                throw new Error(`No provider serves ${request.repo.key}, so there is nowhere to cut a tree from.`);
+            }
+            if (choice.kind === "ambiguous") {
+                const names = choice.providers.map((p) => p.id).join(" and ");
+                throw new Error(`Both ${names} are configured to serve ${request.repo.key}, so which cuts the tree would be arbitrary. Leave one of them out.`);
+            }
+            const { path } = await choice.provider.ensure(request);
+            const held = {
+                identity: treeIdentity(request),
+                path,
+                providerId: choice.provider.id,
+            };
+            trees.push(held);
+            // Awaited, though it costs a `ps` on the way out of every cut.
+            // Left running in the background it is a write that may not
+            // have happened when the caller gets the tree, and a one-shot
+            // session can be gone by then: the record exists precisely so
+            // the next session finds the tree, so losing the race loses
+            // the tree, which is the fault this whole module was written
+            // for. A few milliseconds against cutting a worktree is not a
+            // cost worth that.
+            await memory?.rememberHeldByUs(held);
+            return held;
+        },
+        async release(held) {
+            const all = roster();
+            const owner = all.find((provider) => provider.id === held.providerId);
+            // Nothing to release through, so nothing is released. The record
+            // stays, because it is the only pointer at a directory that is still
+            // there: dropping it is how a tree becomes garbage nothing can name.
+            // A tree that keeps appearing in a listing is recoverable once the
+            // provider loads; one nobody has a record of is not.
+            if (!owner) {
+                return {
+                    kind: "no-provider",
+                    wanted: held.providerId,
+                    registered: all.map((provider) => provider.id),
+                    path: held.path,
+                };
+            }
+            const at = trees.findIndex((tree) => tree.path === held.path);
+            if (at >= 0)
+                trees.splice(at, 1);
+            // Giving up our share of a shared tree is not taking it away.
+            // A snapshot can be held by two sessions, and once this change
+            // started writing that down, releasing had to read it: taking
+            // the directory while somebody else is standing in it is the
+            // failure this whole change is about, arriving through the one
+            // door that always could remove a tree.
+            const others = await memory?.otherHolders(held.path);
+            if (others !== undefined && others.length > 0) {
+                await memory?.forgetUsAsHolder(held.path);
+                return { kind: "released", kept: others.length };
+            }
+            // Forgotten before the provider acts, so a provider that throws
+            // halfway does not leave a record claiming a tree that is now
+            // half-gone. A record for a tree still on disk is recoverable on the
+            // next cut; a record for a broken one is a trap.
+            memory?.forget(held.path);
+            await owner.release(held);
+            return { kind: "released" };
+        },
+        held: () => everything(),
+        cutHere: (path) => trees.some((tree) => tree.path === path),
+    };
+}