@jitsusama/agentic-harness.core 0.6.3 → 0.6.4

package/dist/internal/quest/record-gate.js

@@ -0,0 +1,101 @@
+/**
+ * The record's rules for a single write, applied before it lands.
+ *
+ * A write is refused only when the rule it breaks is certain from the
+ * path alone, and every refusal says where the write belongs instead, so
+ * the refusal is a redirection rather than a dead end. What a path cannot
+ * decide (an attachment's size, whether it is text, whether a document
+ * cites it) is left to the check on disk after the write.
+ *
+ * The rules hold in every quest's folder, not only the loaded quest's,
+ * since a write into another quest's record breaks that record just the
+ * same.
+ */
+import { basename, join } from "node:path";
+import { ATTACHMENTS_FOLDER, attachmentNameProblem, DOCUMENT_FOLDERS, questRecordPath, } from "./record.js";
+import { questWorkspace } from "./workspace.js";
+/** Characters that make a path's name a pattern rather than a name. */
+const GLOB = /[*?[]/;
+/** Judge one write or removal against the record's rules. */
+export function judgeRecordWrite(write, roots) {
+    const place = questRecordPath(roots.questsRoot, write.path);
+    if (!place)
+        return undefined;
+    return write.effect === "remove"
+        ? judgeRemoval(place)
+        : judgeWrite(place, write, roots);
+}
+function judgeRemoval(place) {
+    const { place: kind, rel } = place;
+    const kept = kind === "document" ||
+        kind === "readme" ||
+        kind === "folder" ||
+        kind === "quest" ||
+        (kind === "stray" && isKindFolderPattern(rel));
+    if (!kept)
+        return undefined;
+    const what = kind === "quest" ? `the quest ${place.quest}` : rel;
+    return {
+        rule: "document-removed",
+        reason: `This removes ${what}, which is part of ${place.quest}'s record. ` +
+            "Documents, the README and the record's folders leave only through " +
+            "`quest retire`, which keeps what was written.",
+    };
+}
+function judgeWrite(place, write, roots) {
+    const { place: kind, rel } = place;
+    if (kind === "quest" || kind === "folder")
+        return undefined;
+    if (kind === "document" || kind === "readme") {
+        if (write.via === "bash") {
+            return {
+                rule: "document-by-bash",
+                reason: `This bash command writes into ${rel}. Change a document or the ` +
+                    "README with the edit or write tool instead, so the change is one " +
+                    "the quest's own checks read.",
+            };
+        }
+        if (!write.exists) {
+            return {
+                rule: "document-by-hand",
+                reason: kind === "readme"
+                    ? `${place.quest} has no README to change. A quest and its README are made by \`quest create\`.`
+                    : `${rel} is a new document. Documents are made by \`quest draft\`, which mints the ID and the front matter; run \`quest think\` and then \`quest draft\` instead.`,
+            };
+        }
+        return undefined;
+    }
+    const workspace = questWorkspace(roots.workspaceRoot, place.quest).dir;
+    if (kind === "attachment") {
+        const problem = attachmentNameProblem(rel);
+        if (!problem)
+            return undefined;
+        const instead = join(workspace, rel.slice(ATTACHMENTS_FOLDER.length + 1));
+        return {
+            rule: "attachment",
+            reason: `${rel} is ${problem.detail}, and attachments hold only text and ` +
+                `images a document cites. Put it in the quest's workspace instead: ${instead}`,
+            instead,
+        };
+    }
+    const instead = join(workspace, rel);
+    const citable = attachmentNameProblem(rel) === undefined;
+    return {
+        rule: "stray",
+        reason: `${rel} is not part of ${place.quest}'s record, which holds only its ` +
+            "README, its documents and attachments/. Put it in the quest's " +
+            `workspace instead: ${instead}` +
+            (citable
+                ? `. If a document will cite it, ${ATTACHMENTS_FOLDER}/${basename(rel)} is its place.`
+                : ""),
+        instead,
+    };
+}
+/** Whether a path is a pattern inside a kind folder, which may name documents. */
+function isKindFolderPattern(rel) {
+    const [top, name, ...deeper] = rel.split("/");
+    return (deeper.length === 0 &&
+        name !== undefined &&
+        GLOB.test(name) &&
+        DOCUMENT_FOLDERS.includes(top ?? ""));
+}

package/dist/internal/quest/record.d.ts

@@ -0,0 +1,112 @@
+/**
+ * A quest's record: what in a quest folder is kept, backed up and
+ * protected, and what is not.
+ *
+ * The record is the README, the documents (an ID-named markdown file
+ * directly in a kind folder), and one shared `attachments/` folder that
+ * any document may cite. Everything else a quest makes (clones, raw
+ * data, labs, runs, builds) belongs in its workspace outside the quests
+ * folder, so anything else found inside one is a stray.
+ *
+ * The backup in the dotfiles (`quest-backup`) takes exactly this record
+ * and must work without pi, so it keeps its own copy of these rules. A
+ * change here needs the same change there.
+ */
+/** The folders a quest's documents live in, one per kind. */
+export declare const DOCUMENT_FOLDERS: readonly ["plans", "research", "briefs", "reports"];
+/** The folder a quest's attachments live in. */
+export declare const ATTACHMENTS_FOLDER = "attachments";
+/**
+ * What a path is within a quest's record.
+ *
+ * - `quest`: the quest folder itself.
+ * - `readme`: its README.
+ * - `document`: an ID-named markdown file directly in a kind folder.
+ * - `folder`: a kind folder or the attachments folder itself.
+ * - `attachment`: anything beneath the attachments folder.
+ * - `stray`: anything else, which belongs in the workspace.
+ */
+export type RecordPlace = "quest" | "readme" | "document" | "folder" | "attachment" | "stray";
+/** A path inside a quest folder, and what it is there. */
+export interface QuestRecordPath {
+    /** The quest's ID. */
+    readonly quest: string;
+    /** The quest's folder. */
+    readonly questDir: string;
+    /** The path relative to the quest's folder, `""` for the folder itself. */
+    readonly rel: string;
+    readonly place: RecordPlace;
+}
+/**
+ * Which quest an absolute path belongs to and what it is there, or
+ * undefined when it is not inside a quest folder.
+ *
+ * Quests sit directly under the quests root, one folder named by the
+ * quest's ID, so the first segment beneath the root decides the quest.
+ */
+export declare function questRecordPath(questsRoot: string, path: string): QuestRecordPath | undefined;
+/**
+ * What an attachment may be. Text, read as a file with no NUL byte in
+ * its first `sniffBytes`, up to `textBytes`; a raster image up to
+ * `imageBytes`. The backup keeps the same numbers.
+ */
+export declare const ATTACHMENT_LIMITS: {
+    readonly textBytes: number;
+    readonly imageBytes: number;
+    readonly sniffBytes: 8192;
+};
+/** What is known about a file that might be an attachment. */
+export interface AttachmentFile {
+    /** The path relative to the quest's folder. */
+    readonly rel: string;
+    readonly kind: "file" | "symlink" | "directory" | "other";
+    readonly size: number;
+    /** The file's first bytes, at least `sniffBytes` of them when it has that many. */
+    readonly head: Uint8Array;
+}
+/** Why a file cannot be an attachment. */
+export interface AttachmentProblem {
+    readonly reason: "not-a-file" | "in-a-checkout" | "raw-data" | "binary" | "too-large";
+    /** The same, in words a refusal can quote. */
+    readonly detail: string;
+}
+/**
+ * Why a path cannot be an attachment, as far as its name decides: a path
+ * inside a git checkout, or a raw-data type. Undefined when the name
+ * allows it, which does not yet mean the file does.
+ */
+export declare function attachmentNameProblem(rel: string): AttachmentProblem | undefined;
+/**
+ * Why a file cannot be an attachment, or undefined when it can. A folder
+ * is fine, since it only holds attachments, unless it is a checkout's
+ * `.git`.
+ */
+export declare function attachmentProblem(file: AttachmentFile): AttachmentProblem | undefined;
+/** Which documents cite each attachment, and the links that lead nowhere. */
+export interface AttachmentCitations {
+    /** Each cited attachment's quest-relative path, and who cites it. */
+    readonly cited: Map<string, string[]>;
+    /** Links into `attachments/` that name no attachment, as written. */
+    readonly broken: {
+        document: string;
+        target: string;
+    }[];
+}
+/**
+ * Which of a quest's documents cite each of its attachments.
+ *
+ * Documents live in the quest folder or one level down, so any mention
+ * of an attachment runs through `attachments/`, whichever way it is
+ * written: a link, an image, a reference definition, a code span, or a
+ * path in prose or a code block. A mention of a folder cites everything
+ * in it, and a glob cites the folder it starts in. A mention that names
+ * another quest's folder is that quest's business.
+ *
+ * Only a link can be broken. Prose often names a path that does not exist
+ * yet ("put the chart in attachments/cost.png"), while a link that goes
+ * nowhere is a record that lost its attachment.
+ */
+export declare function attachmentCitations(quest: string, documents: readonly {
+    rel: string;
+    text: string;
+}[], attachments: readonly string[]): AttachmentCitations;

package/dist/internal/quest/record.js

@@ -0,0 +1,284 @@
+/**
+ * A quest's record: what in a quest folder is kept, backed up and
+ * protected, and what is not.
+ *
+ * The record is the README, the documents (an ID-named markdown file
+ * directly in a kind folder), and one shared `attachments/` folder that
+ * any document may cite. Everything else a quest makes (clones, raw
+ * data, labs, runs, builds) belongs in its workspace outside the quests
+ * folder, so anything else found inside one is a stray.
+ *
+ * The backup in the dotfiles (`quest-backup`) takes exactly this record
+ * and must work without pi, so it keeps its own copy of these rules. A
+ * change here needs the same change there.
+ */
+import { isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { isId, prefixOf } from "./id.js";
+/** The folders a quest's documents live in, one per kind. */
+export const DOCUMENT_FOLDERS = [
+    "plans",
+    "research",
+    "briefs",
+    "reports",
+];
+/** The folder a quest's attachments live in. */
+export const ATTACHMENTS_FOLDER = "attachments";
+/**
+ * Which quest an absolute path belongs to and what it is there, or
+ * undefined when it is not inside a quest folder.
+ *
+ * Quests sit directly under the quests root, one folder named by the
+ * quest's ID, so the first segment beneath the root decides the quest.
+ */
+export function questRecordPath(questsRoot, path) {
+    if (!isAbsolute(path))
+        return undefined;
+    const fromRoot = relative(resolve(questsRoot), resolve(path));
+    if (!fromRoot || fromRoot.startsWith("..") || isAbsolute(fromRoot)) {
+        return undefined;
+    }
+    const [quest, ...rest] = fromRoot.split(sep);
+    if (quest === undefined || prefixOf(quest) !== "QEST")
+        return undefined;
+    const rel = rest.join("/");
+    return {
+        quest,
+        questDir: join(resolve(questsRoot), quest),
+        rel,
+        place: placeOf(rest),
+    };
+}
+/** What a quest-relative path, given as its segments, is. */
+function placeOf(segments) {
+    const [top, name, ...deeper] = segments;
+    if (top === undefined)
+        return "quest";
+    if (top === ATTACHMENTS_FOLDER) {
+        return name === undefined ? "folder" : "attachment";
+    }
+    if (top === "README.md" && name === undefined)
+        return "readme";
+    if (!isKindFolder(top))
+        return "stray";
+    if (name === undefined)
+        return "folder";
+    if (deeper.length > 0 || !isDocumentName(name))
+        return "stray";
+    return "document";
+}
+function isKindFolder(name) {
+    return DOCUMENT_FOLDERS.includes(name);
+}
+/**
+ * What an attachment may be. Text, read as a file with no NUL byte in
+ * its first `sniffBytes`, up to `textBytes`; a raster image up to
+ * `imageBytes`. The backup keeps the same numbers.
+ */
+export const ATTACHMENT_LIMITS = {
+    textBytes: 1024 * 1024,
+    imageBytes: 5 * 1024 * 1024,
+    sniffBytes: 8192,
+};
+/** Raster image types, which are the one binary an attachment may be. */
+const IMAGE_TYPES = new Set([
+    "png",
+    "jpg",
+    "jpeg",
+    "gif",
+    "webp",
+    "avif",
+    "heic",
+    "bmp",
+    "ico",
+]);
+/**
+ * Types that hold raw data rather than something a document cites:
+ * databases, archives, git objects, logs, traces, dumps and builds. Their
+ * home is the workspace even when they happen to be small or text.
+ */
+const RAW_DATA_TYPES = new Set([
+    "db",
+    "sqlite",
+    "sqlite3",
+    "zip",
+    "tar",
+    "tgz",
+    "gz",
+    "zst",
+    "xz",
+    "bz2",
+    "7z",
+    "pack",
+    "idx",
+    "jsonl",
+    "ndjson",
+    "log",
+    "trace",
+    "pcap",
+    "dump",
+    "core",
+    "heapsnapshot",
+    "cpuprofile",
+    "slab",
+    "bin",
+    "parquet",
+    "arrow",
+    "wasm",
+    "o",
+    "a",
+    "so",
+    "dylib",
+    "jar",
+    "class",
+    "pyc",
+]);
+/**
+ * Why a path cannot be an attachment, as far as its name decides: a path
+ * inside a git checkout, or a raw-data type. Undefined when the name
+ * allows it, which does not yet mean the file does.
+ */
+export function attachmentNameProblem(rel) {
+    if (rel.split("/").includes(".git")) {
+        return { reason: "in-a-checkout", detail: "part of a git checkout" };
+    }
+    const type = typeOf(rel);
+    if (type !== undefined && RAW_DATA_TYPES.has(type)) {
+        return { reason: "raw-data", detail: `a .${type} file, which is raw data` };
+    }
+    return undefined;
+}
+/**
+ * Why a file cannot be an attachment, or undefined when it can. A folder
+ * is fine, since it only holds attachments, unless it is a checkout's
+ * `.git`.
+ */
+export function attachmentProblem(file) {
+    const named = attachmentNameProblem(file.rel);
+    if (named)
+        return named;
+    if (file.kind === "directory")
+        return undefined;
+    if (file.kind !== "file") {
+        return {
+            reason: "not-a-file",
+            detail: `a ${file.kind}, not a regular file`,
+        };
+    }
+    const type = typeOf(file.rel);
+    if (type !== undefined && IMAGE_TYPES.has(type)) {
+        return overLimit(file.size, ATTACHMENT_LIMITS.imageBytes, "image");
+    }
+    const sniffed = file.head.subarray(0, ATTACHMENT_LIMITS.sniffBytes);
+    if (sniffed.includes(0)) {
+        return { reason: "binary", detail: "binary, neither text nor an image" };
+    }
+    return overLimit(file.size, ATTACHMENT_LIMITS.textBytes, "text");
+}
+/** A markdown link or image target, inline or as a reference definition. */
+const LINK_TARGET = /\]\(\s*(<[^>\n]+>|[^)\s]+)|^ {0,3}\[[^\]\n]+\]:[ \t]*(<[^>\n]+>|\S+)/gm;
+/** Any path-like run of text that goes through an `attachments/` folder. */
+const MENTION = new RegExp(`[^\\s\`'"()<>\\[\\]|,;]*${ATTACHMENTS_FOLDER}/[^\\s\`'"()<>\\[\\]|,;]*`, "g");
+const QUEST_ID = /QEST-\d{8}-[0-9A-Z]{6}/g;
+/**
+ * Which of a quest's documents cite each of its attachments.
+ *
+ * Documents live in the quest folder or one level down, so any mention
+ * of an attachment runs through `attachments/`, whichever way it is
+ * written: a link, an image, a reference definition, a code span, or a
+ * path in prose or a code block. A mention of a folder cites everything
+ * in it, and a glob cites the folder it starts in. A mention that names
+ * another quest's folder is that quest's business.
+ *
+ * Only a link can be broken. Prose often names a path that does not exist
+ * yet ("put the chart in attachments/cost.png"), while a link that goes
+ * nowhere is a record that lost its attachment.
+ */
+export function attachmentCitations(quest, documents, attachments) {
+    const cited = new Map();
+    const broken = [];
+    const credit = (document, mention) => {
+        const key = attachmentKey(quest, mention);
+        if (key === undefined)
+            return true;
+        const matches = attachments.filter((attachment) => attachment === key || attachment.startsWith(`${key}/`));
+        for (const attachment of matches) {
+            const citers = cited.get(attachment) ?? [];
+            if (!citers.includes(document))
+                citers.push(document);
+            cited.set(attachment, citers);
+        }
+        return matches.length > 0;
+    };
+    for (const { rel, text } of documents) {
+        for (const match of text.matchAll(LINK_TARGET)) {
+            const written = (match[1] ?? match[2] ?? "").replace(/^<|>$/g, "");
+            const target = decoded(written.replace(/[#?].*$/, ""));
+            if (!target.includes(`${ATTACHMENTS_FOLDER}/`))
+                continue;
+            if (!credit(rel, target))
+                broken.push({ document: rel, target: written });
+        }
+        for (const [mention] of text.matchAll(MENTION))
+            credit(rel, mention);
+    }
+    return { cited, broken };
+}
+/**
+ * The quest-relative path a mention names under `attachments/`, or
+ * undefined when it names another quest's, the folder as a whole, or
+ * nothing that stays inside it.
+ */
+function attachmentKey(quest, mention) {
+    const ids = mention.match(QUEST_ID) ?? [];
+    const owner = ids.at(-1);
+    if (owner !== undefined && owner !== quest)
+        return undefined;
+    const marker = `${ATTACHMENTS_FOLDER}/`;
+    const after = owner === undefined ? 0 : mention.lastIndexOf(owner);
+    const at = mention.indexOf(marker, after);
+    if (at < 0)
+        return undefined;
+    let within = mention.slice(at + marker.length).replace(/[#?].*$/, "");
+    const glob = within.search(/[*?[{]/);
+    if (glob >= 0)
+        within = within.slice(0, within.lastIndexOf("/", glob) + 1);
+    within = within.replace(/[.:;!?*_]+$/, "");
+    const normal = posix.normalize(within).replace(/\/+$/, "");
+    if (!normal || normal === "." || normal.startsWith(".."))
+        return undefined;
+    return `${marker}${normal}`;
+}
+/** A link target with its percent-encoding undone, or as written when malformed. */
+function decoded(target) {
+    try {
+        return decodeURI(target);
+    }
+    catch {
+        return target;
+    }
+}
+/** A size problem when `size` is over `limit`. */
+function overLimit(size, limit, what) {
+    if (size <= limit)
+        return undefined;
+    return {
+        reason: "too-large",
+        detail: `${mebibytes(size, 1)} MiB of ${what}, over the ${mebibytes(limit, 0)} MiB limit`,
+    };
+}
+function mebibytes(bytes, digits) {
+    return (bytes / (1024 * 1024)).toFixed(digits);
+}
+/** A file's type, its last extension lowercased, or undefined without one. */
+function typeOf(rel) {
+    const name = rel.split("/").at(-1) ?? "";
+    const dot = name.lastIndexOf(".");
+    return dot > 0 ? name.slice(dot + 1).toLowerCase() : undefined;
+}
+/** Whether a file name is a document's: a non-quest ID with `.md`. */
+function isDocumentName(name) {
+    if (!name.endsWith(".md"))
+        return false;
+    const id = name.slice(0, -3);
+    return isId(id) && prefixOf(id) !== "QEST";
+}

package/dist/internal/quest/workspace.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A quest's workspace: where everything a quest makes that is not its
+ * record lives, such as clones, raw data, labs, runs and builds.
+ *
+ * It sits outside the quests folder, under a root the adapter chooses
+ * (pi's is its cache directory), in a folder named by the quest's ID, so
+ * anything outside pi can find a workspace's quest by name alone. Its
+ * `tmp/` takes the ad-hoc writes that would otherwise land in system
+ * temp, and is the one part a conclude clears. The rest outlives the
+ * quest for a while and is reclaimed by the disk guard, which also
+ * compresses a concluded quest's workspace; neither is done here, since
+ * both are slow and belong to the host.
+ */
+/** A quest's workspace folder and its `tmp/`. */
+export interface QuestWorkspace {
+    readonly dir: string;
+    readonly tmp: string;
+}
+/**
+ * Where a quest's workspace is. Refuses anything that is not a quest's
+ * ID, since the folder is created and emptied by name and a name like
+ * `../x` would reach outside the root.
+ */
+export declare function questWorkspace(root: string, questId: string): QuestWorkspace;
+/** A quest's `tmp/`, created on first need. */
+export declare function ensureQuestWorkspaceTmp(root: string, questId: string): string;
+/**
+ * Empty a quest's `tmp/` and leave the rest of its workspace. Returns
+ * whether there was one to clear. Best-effort, as reaping scratch was: a
+ * wedged file must not stop a quest from concluding.
+ */
+export declare function clearQuestWorkspaceTmp(root: string, questId: string): boolean;

package/dist/internal/quest/workspace.js

@@ -0,0 +1,51 @@
+/**
+ * A quest's workspace: where everything a quest makes that is not its
+ * record lives, such as clones, raw data, labs, runs and builds.
+ *
+ * It sits outside the quests folder, under a root the adapter chooses
+ * (pi's is its cache directory), in a folder named by the quest's ID, so
+ * anything outside pi can find a workspace's quest by name alone. Its
+ * `tmp/` takes the ad-hoc writes that would otherwise land in system
+ * temp, and is the one part a conclude clears. The rest outlives the
+ * quest for a while and is reclaimed by the disk guard, which also
+ * compresses a concluded quest's workspace; neither is done here, since
+ * both are slow and belong to the host.
+ */
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { isId, prefixOf } from "./id.js";
+/**
+ * Where a quest's workspace is. Refuses anything that is not a quest's
+ * ID, since the folder is created and emptied by name and a name like
+ * `../x` would reach outside the root.
+ */
+export function questWorkspace(root, questId) {
+    if (!isId(questId) || prefixOf(questId) !== "QEST") {
+        throw new Error(`"${questId}" is not a quest ID.`);
+    }
+    const dir = join(root, questId);
+    return { dir, tmp: join(dir, "tmp") };
+}
+/** A quest's `tmp/`, created on first need. */
+export function ensureQuestWorkspaceTmp(root, questId) {
+    const { tmp } = questWorkspace(root, questId);
+    mkdirSync(tmp, { recursive: true });
+    return tmp;
+}
+/**
+ * Empty a quest's `tmp/` and leave the rest of its workspace. Returns
+ * whether there was one to clear. Best-effort, as reaping scratch was: a
+ * wedged file must not stop a quest from concluding.
+ */
+export function clearQuestWorkspaceTmp(root, questId) {
+    const { tmp } = questWorkspace(root, questId);
+    if (!existsSync(tmp))
+        return false;
+    try {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    catch {
+        // Left for the disk guard, which reclaims the whole workspace later.
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jitsusama/agentic-harness.core",
-	"version": "0.6.3",
+	"version": "0.6.4",
 	"description": "Pi-agnostic business logic for agentic-harness: state machines, guardian decisions, quest/TDD domain model.",
 	"license": "MIT",
 	"type": "module",
@@ -45,6 +45,12 @@
 		"./quest/verbs/queries": "./dist/quest/verbs/queries.js",
 		"./quest/verbs/lifecycle": "./dist/quest/verbs/lifecycle.js",
 		"./quest/verbs/tree-ops": "./dist/quest/verbs/tree-ops.js",
+		"./quest/bash-write": "./dist/internal/quest/bash-write.js",
+		"./quest/write-classifier": "./dist/internal/quest/write-classifier.js",
+		"./quest/record": "./dist/internal/quest/record.js",
+		"./quest/workspace": "./dist/internal/quest/workspace.js",
+		"./quest/record-gate": "./dist/internal/quest/record-gate.js",
+		"./quest/record-audit": "./dist/internal/quest/record-audit.js",
 		"./tree": "./dist/tree/index.js",
 		"./lsp": "./dist/lsp/index.js",
 		"./result": "./dist/result/index.js",