@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/quest/resolve-cwd.js

@@ -0,0 +1,89 @@
+/**
+ * Which quest a working directory belongs to.
+ *
+ * The explicit load verb and the session-start restore both need this
+ * answer, and both used to compute it themselves. The two copies were
+ * kept in step by a comment asking the next reader to keep them in
+ * step, and they had already drifted: one `isUnder` compared against a
+ * hardcoded slash and the other against the platform separator.
+ *
+ * Taking the discovered index rather than reading the disk keeps this
+ * a decision rather than an errand, so the preference rules can be
+ * tested directly instead of through a temp directory and a session.
+ */
+import { realpathSync } from "node:fs";
+import { sep } from "node:path";
+import { isSealedStatus } from "./status.js";
+/**
+ * Resolve symlinks so /var and /private/var, and bind mounts in a
+ * container, compare equal. A path that does not exist is its own
+ * answer: comparing the literal string is better than refusing.
+ */
+function canonical(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/** Whether `child` is `parent` or sits underneath it. */
+function isUnder(child, parent) {
+    if (child === parent)
+        return true;
+    return child.startsWith(`${parent}${sep}`);
+}
+/**
+ * The id of the quest that owns `cwd`, or undefined if none does.
+ *
+ * A quest's own directory is the strongest claim. Failing that, the
+ * deepest scaffolded working tree covering the cwd wins, so a tree
+ * nested inside another resolves to its immediate owner.
+ *
+ * A live quest beats a sealed one wherever both cover the cwd, so a
+ * fresh session started inside a finished quest's tree does not
+ * attach to the finished quest. Note this gates resolution only:
+ * whether a sealed quest still owns a tree on disk is a different
+ * question, and the answer there is that it does.
+ *
+ * Only `scaffolded` trees magnetize. An adopted or unmarked tree, and
+ * a `git-worktree:` alias, is a reference to a checkout several quests
+ * may name, so resolving through one would pick an arbitrary owner.
+ */
+export function questIdForCwd(index, cwd) {
+    const target = canonical(cwd);
+    let dirMatch;
+    let dirMatchLive = false;
+    for (const entry of index.quests.values()) {
+        if (!isUnder(target, canonical(entry.dir)))
+            continue;
+        const live = !isSealedStatus(entry.doc.frontMatter.status);
+        if (dirMatch === undefined || (live && !dirMatchLive)) {
+            dirMatch = entry.doc.frontMatter.id;
+            dirMatchLive = live;
+        }
+    }
+    if (dirMatch !== undefined)
+        return dirMatch;
+    let bestId;
+    let bestLen = -1;
+    let bestLive = false;
+    for (const entry of index.quests.values()) {
+        const fm = entry.doc.frontMatter;
+        const live = !isSealedStatus(fm.status);
+        for (const tree of fm.trees ?? []) {
+            if (tree.origin !== "scaffolded")
+                continue;
+            const real = canonical(tree.path);
+            if (!isUnder(target, real))
+                continue;
+            if (real.length > bestLen ||
+                (real.length === bestLen && live && !bestLive)) {
+                bestLen = real.length;
+                bestId = fm.id;
+                bestLive = live;
+            }
+        }
+    }
+    return bestId;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Sanitizers for text that flows from external sources
+ * (GitHub PR titles, issue bodies, third-party author
+ * handles) into a quest README that the agent then reads
+ * back as part of its context.
+ *
+ * The concern is not classic XSS: the README is markdown
+ * the agent renders. The concern is that an attacker who
+ * controls a PR title or body can shape the structure of
+ * the README so the agent reads it as instructions ("##
+ * Important: ignore all prior instructions"). We strip
+ * the structural markers we know the README parser cares
+ * about, and clamp lengths so a hostile excerpt cannot
+ * shove the rest of the document out of the agent's
+ * context window.
+ *
+ * These helpers are defensive, not exhaustive. Callers
+ * should think about what they're templating in.
+ */
+/**
+ * Strip newlines, collapse whitespace and clamp length.
+ * Use for single-line fields: titles, handles, captions.
+ */
+export declare function sanitizeSingleLine(value: string, maxLen?: number): string;
+/**
+ * Escape leading markdown structure markers so a hostile
+ * excerpt cannot pose as a heading, bullet, code fence or
+ * frontmatter delimiter on its own line. Each affected
+ * line gets a leading zero-width space, which renders
+ * invisibly but breaks the regex-anchored markdown
+ * extractors the quest tooling uses.
+ *
+ * Newlines inside the value are preserved.
+ */
+export declare function escapeMarkdownStructure(value: string): string;
+/**
+ * Sanitize an excerpt: clamp length, escape leading
+ * structure markers, strip carriage returns.
+ */
+export declare function sanitizeExcerpt(value: string): string;
+/** Sanitize a handle for inline display (`@<login>`). */
+export declare function sanitizeHandle(value: string): string;

package/dist/internal/quest/sanitize.js

@@ -0,0 +1,69 @@
+/**
+ * Sanitizers for text that flows from external sources
+ * (GitHub PR titles, issue bodies, third-party author
+ * handles) into a quest README that the agent then reads
+ * back as part of its context.
+ *
+ * The concern is not classic XSS: the README is markdown
+ * the agent renders. The concern is that an attacker who
+ * controls a PR title or body can shape the structure of
+ * the README so the agent reads it as instructions ("##
+ * Important: ignore all prior instructions"). We strip
+ * the structural markers we know the README parser cares
+ * about, and clamp lengths so a hostile excerpt cannot
+ * shove the rest of the document out of the agent's
+ * context window.
+ *
+ * These helpers are defensive, not exhaustive. Callers
+ * should think about what they're templating in.
+ */
+const MAX_TITLE_LENGTH = 200;
+const MAX_HANDLE_LENGTH = 64;
+const MAX_EXCERPT_LENGTH = 400;
+/**
+ * Strip newlines, collapse whitespace and clamp length.
+ * Use for single-line fields: titles, handles, captions.
+ */
+export function sanitizeSingleLine(value, maxLen = MAX_TITLE_LENGTH) {
+    return value
+        .replace(/[\r\n]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, maxLen);
+}
+/**
+ * Escape leading markdown structure markers so a hostile
+ * excerpt cannot pose as a heading, bullet, code fence or
+ * frontmatter delimiter on its own line. Each affected
+ * line gets a leading zero-width space, which renders
+ * invisibly but breaks the regex-anchored markdown
+ * extractors the quest tooling uses.
+ *
+ * Newlines inside the value are preserved.
+ */
+export function escapeMarkdownStructure(value) {
+    return value
+        .split("\n")
+        .map((line) => {
+        if (/^\s*(#|---|```|>|\*\s|-\s|\d+\.\s)/.test(line)) {
+            return `\u200b${line}`;
+        }
+        return line;
+    })
+        .join("\n");
+}
+/**
+ * Sanitize an excerpt: clamp length, escape leading
+ * structure markers, strip carriage returns.
+ */
+export function sanitizeExcerpt(value) {
+    const trimmed = value.replace(/\r/g, "").trim();
+    const clamped = trimmed.length > MAX_EXCERPT_LENGTH
+        ? `${trimmed.slice(0, MAX_EXCERPT_LENGTH)}...`
+        : trimmed;
+    return escapeMarkdownStructure(clamped);
+}
+/** Sanitize a handle for inline display (`@<login>`). */
+export function sanitizeHandle(value) {
+    return sanitizeSingleLine(value, MAX_HANDLE_LENGTH).replace(/[^A-Za-z0-9._-]/g, "");
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Document scaffolding: build the initial markdown body for
+ * a new quest README or a new quest document.
+ *
+ * The scaffolded body is a starting shape with the canonical
+ * section headers (and emoji glyphs) and one-line guidance
+ * underneath each. Authors are expected to overwrite the
+ * guidance immediately; the structure makes the round-trip
+ * parsing reliable.
+ *
+ * Optional sections (Milestones, Spirit, Outcomes, Context)
+ * are emitted as commented placeholders the author uncomments
+ * when they need them. We do not enforce their presence.
+ */
+import type { DocumentFrontMatter, QuestFrontMatter, QuestKind } from "../../quest/types.js";
+/** Inputs for scaffolding a fresh quest README. */
+export interface QuestScaffoldInput {
+    frontMatter: QuestFrontMatter;
+    title: string;
+    /** Optional initial Summary prose. */
+    summary?: string;
+    /** Optional initial Purpose prose. */
+    purpose?: string;
+    /** Optional initial Cast bullets. */
+    cast?: Array<{
+        role: string;
+        subject: string;
+        prose?: string;
+    }>;
+    /** Optional initial Journey entry. */
+    journey?: Array<{
+        date: string;
+        prose: string;
+    }>;
+    /** Optional Milestones bullets. */
+    milestones?: Array<{
+        checked: boolean;
+        text: string;
+    }>;
+    /** Include the optional sections as placeholders. */
+    includeOptionalSections?: boolean;
+}
+/**
+ * Build a fresh quest README. The four core sections are
+ * always present; optional sections appear behind a
+ * commented marker unless `includeOptionalSections` is true.
+ */
+export declare function scaffoldQuestReadme(input: QuestScaffoldInput): string;
+/** Inputs for scaffolding a quest document (plan/research/etc.). */
+export interface DocumentScaffoldInput {
+    frontMatter: DocumentFrontMatter;
+    title: string;
+}
+/** Build a fresh quest document with the kind's section template. */
+export declare function scaffoldDocument(input: DocumentScaffoldInput): string;
+/** Convenience: map quest kind to the default scaffold options. */
+export declare function defaultsForKind(_kind: QuestKind): {
+    includeOptionalSections: boolean;
+};

package/dist/internal/quest/scaffold.js

@@ -0,0 +1,169 @@
+/**
+ * Document scaffolding: build the initial markdown body for
+ * a new quest README or a new quest document.
+ *
+ * The scaffolded body is a starting shape with the canonical
+ * section headers (and emoji glyphs) and one-line guidance
+ * underneath each. Authors are expected to overwrite the
+ * guidance immediately; the structure makes the round-trip
+ * parsing reliable.
+ *
+ * Optional sections (Milestones, Spirit, Outcomes, Context)
+ * are emitted as commented placeholders the author uncomments
+ * when they need them. We do not enforce their presence.
+ */
+import { wrapProse } from "../../prose/wrap.js";
+import { serializeDocumentFrontMatter, serializeQuestFrontMatter, } from "./frontmatter.js";
+function castBullet(entry) {
+    const role = entry.role.toLowerCase();
+    const tail = entry.prose ? `. ${entry.prose}` : "";
+    return `- **${role}**: ${entry.subject}${tail}`;
+}
+function journeyBullet(entry) {
+    return `- **${entry.date}**: ${entry.prose}`;
+}
+function milestoneBullet(entry) {
+    return `- [${entry.checked ? "x" : " "}] ${entry.text}`;
+}
+/**
+ * Build a fresh quest README. The four core sections are
+ * always present; optional sections appear behind a
+ * commented marker unless `includeOptionalSections` is true.
+ */
+export function scaffoldQuestReadme(input) {
+    const fm = serializeQuestFrontMatter(input.frontMatter);
+    const parts = [fm, "", `# ${input.title}`, ""];
+    // Wrapped on the way in, so a quest is born meeting the column rule
+    // its own plan documents are held to. A summary arrives as one long
+    // line, since it is assembled from a note and a seeded excerpt, and
+    // nothing downstream was rewrapping it.
+    parts.push("## 📜 Summary", "");
+    parts.push(wrapProse(input.summary ?? "_One paragraph: what this quest is and why it exists._"), "");
+    parts.push("## 🧭 Purpose", "");
+    parts.push(wrapProse(input.purpose ?? "_Why now, what good looks like, what is in scope._"), "");
+    parts.push("## 🎭 Cast", "");
+    if (input.cast && input.cast.length > 0) {
+        for (const entry of input.cast)
+            parts.push(castBullet(entry));
+    }
+    else {
+        parts.push("- **owner**: _name or @handle_");
+    }
+    parts.push("");
+    parts.push("## 🌄 Journey", "");
+    if (input.journey && input.journey.length > 0) {
+        for (const entry of input.journey)
+            parts.push(journeyBullet(entry));
+    }
+    else {
+        parts.push(`- **${input.frontMatter.started}**: Created.`);
+    }
+    parts.push("");
+    const milestones = input.milestones ?? [];
+    if (input.includeOptionalSections || milestones.length > 0) {
+        parts.push("## 🎯 Milestones", "");
+        if (milestones.length > 0) {
+            for (const m of milestones)
+                parts.push(milestoneBullet(m));
+        }
+        else {
+            parts.push("- [ ] _first milestone_");
+        }
+        parts.push("");
+    }
+    if (input.includeOptionalSections) {
+        parts.push("## 🔥 Spirit", "", "_The stable north star that survives deviation._", "");
+        parts.push("## 🏆 Outcomes", "", "_What landed when this quest concluded._", "");
+        parts.push("## 🏰 Context", "", "_Background that doesn't fit in Summary or Purpose._", "");
+    }
+    return parts.join("\n");
+}
+const DOCUMENT_KIND_HEADINGS = {
+    plan: [
+        "## Spirit",
+        "",
+        "_The stable north star: why this work exists and what good looks like._",
+        "",
+        "## Context",
+        "",
+        "_What framing the problem surfaced. Constraints. Scope._",
+        "",
+        "## Approach",
+        "",
+        "_The shape we settled on and the decisions behind it._",
+        "",
+        "## Work",
+        "",
+        "- [ ] _first checklist item_",
+        "",
+        "## Open Questions",
+        "",
+        "_Decisions still pending. Each with a recommended lean._",
+        "",
+        "## Discovery & Deviations",
+        "",
+        "_Things learned during build that changed the plan._",
+        "",
+    ],
+    research: [
+        "## Question",
+        "",
+        "_The thing we're trying to answer._",
+        "",
+        "## Method",
+        "",
+        "_How the investigation proceeded._",
+        "",
+        "## Findings",
+        "",
+        "_What we learned._",
+        "",
+        "## Verdict",
+        "",
+        "_The recommendation that came out of the investigation._",
+        "",
+    ],
+    brief: [
+        "## Audience",
+        "",
+        "_Who this brief is for._",
+        "",
+        "## Ask",
+        "",
+        "_What we want them to do or decide._",
+        "",
+        "## Background",
+        "",
+        "_The minimal context needed to act._",
+        "",
+        "## Recommendation",
+        "",
+        "_What we propose._",
+        "",
+    ],
+    report: [
+        "## What Happened",
+        "",
+        "_The narrative of the work._",
+        "",
+        "## Outcomes",
+        "",
+        "_What landed, what didn't._",
+        "",
+        "## Lessons",
+        "",
+        "_What we learned for next time._",
+        "",
+    ],
+};
+/** Build a fresh quest document with the kind's section template. */
+export function scaffoldDocument(input) {
+    const fm = serializeDocumentFrontMatter(input.frontMatter);
+    const sections = DOCUMENT_KIND_HEADINGS[input.frontMatter.kind];
+    const parts = [fm, "", `# ${input.title}`, "", ...sections];
+    return parts.join("\n");
+}
+/** Convenience: map quest kind to the default scaffold options. */
+export function defaultsForKind(_kind) {
+    return { includeOptionalSections: false };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * The quest's managed scratch directory: a reapable space the gate
+ * funnels ad-hoc writes into. It is created on demand under the OS
+ * temp dir, so it lands on whatever volume the system designates as
+ * temp (honouring $TMPDIR) and carries a unique mkdtemp namespace
+ * the kernel guarantees is fresh. The path is persisted on the
+ * quest frontmatter so it survives across sessions and can be
+ * reaped on conclude or retire.
+ */
+/**
+ * Return the quest's managed scratch directory, creating and
+ * recording it on first need. The whole check-create-persist runs
+ * under one quest lock with the frontmatter as the source of truth:
+ * a racing session that recorded a dir first wins, and we reuse it
+ * rather than stranding a second mkdtemp. The frontmatter is read
+ * and parsed before any directory is created, so a malformed README
+ * fails loud instead of orphaning an unrecorded dir.
+ */
+export declare function ensureQuestScratchDir(questDir: string, questId: string, current: string | null): string;
+/**
+ * Remove the quest's managed scratch directory and clear the
+ * persisted path. Returns whether a directory was recorded to reap.
+ * The delete is contained to a real managed-scratch path and is
+ * best-effort: a wedged or failed removal must not block conclude or
+ * retire. The frontmatter reference is always cleared.
+ */
+export declare function reapQuestScratchDir(questDir: string, current: string | null): boolean;

package/dist/internal/quest/scratch.js

@@ -0,0 +1,106 @@
+/**
+ * The quest's managed scratch directory: a reapable space the gate
+ * funnels ad-hoc writes into. It is created on demand under the OS
+ * temp dir, so it lands on whatever volume the system designates as
+ * temp (honouring $TMPDIR) and carries a unique mkdtemp namespace
+ * the kernel guarantees is fresh. The path is persisted on the
+ * quest frontmatter so it survives across sessions and can be
+ * reaped on conclude or retire.
+ */
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { parseQuestFrontMatter, serializeReadable } from "./frontmatter.js";
+import { isWithin } from "./git-signals.js";
+import { atomicWriteFile, withQuestLock } from "./io.js";
+/** The basename prefix every managed scratch dir carries. */
+const SCRATCH_PREFIX = "pi-quest-";
+/** Path to a quest's README. */
+function questReadme(questDir) {
+    return join(questDir, "README.md");
+}
+/**
+ * Write the quest's scratchDir into already-parsed frontmatter,
+ * preserving the body, using the atomic torn-read-safe write the
+ * other quest writers use. The caller holds the quest lock.
+ *
+ * Refuses rather than writing a README the strict parser cannot read
+ * back, which this writer alone used to skip. A scratch path is
+ * ordinary text and the failure it caused was not: an unreadable
+ * README drops the quest out of discovery entirely, and the write
+ * that did it reported success.
+ */
+function writeScratchDir(path, parsed, value) {
+    const fm = { ...parsed.frontMatter };
+    if (value)
+        fm.scratchDir = value;
+    else
+        delete fm.scratchDir;
+    const serialized = serializeReadable(fm, parsed.body);
+    if (!serialized.ok)
+        throw new Error(serialized.reason);
+    atomicWriteFile(path, serialized.text);
+}
+/**
+ * Whether a recorded path is safe to recursively delete: it must sit
+ * under the OS temp dir and carry the managed-scratch prefix. A
+ * stale, hand-edited or symlinked frontmatter value that fails this
+ * is left untouched, so the reap can never rm -rf an arbitrary path.
+ */
+function isReapableScratch(dir) {
+    return isWithin(dir, tmpdir()) && basename(dir).startsWith(SCRATCH_PREFIX);
+}
+/**
+ * Return the quest's managed scratch directory, creating and
+ * recording it on first need. The whole check-create-persist runs
+ * under one quest lock with the frontmatter as the source of truth:
+ * a racing session that recorded a dir first wins, and we reuse it
+ * rather than stranding a second mkdtemp. The frontmatter is read
+ * and parsed before any directory is created, so a malformed README
+ * fails loud instead of orphaning an unrecorded dir.
+ */
+export function ensureQuestScratchDir(questDir, questId, current) {
+    if (current && existsSync(current))
+        return current;
+    return withQuestLock(questDir, () => {
+        const path = questReadme(questDir);
+        const parsed = parseQuestFrontMatter(readFileSync(path, "utf8"));
+        if (!parsed) {
+            throw new Error(`Quest README at ${path} has no parseable front matter.`);
+        }
+        const recorded = parsed.frontMatter.scratchDir;
+        if (recorded && existsSync(recorded))
+            return recorded;
+        const dir = mkdtempSync(join(tmpdir(), `${SCRATCH_PREFIX}${questId}-`));
+        writeScratchDir(path, parsed, dir);
+        return dir;
+    });
+}
+/**
+ * Remove the quest's managed scratch directory and clear the
+ * persisted path. Returns whether a directory was recorded to reap.
+ * The delete is contained to a real managed-scratch path and is
+ * best-effort: a wedged or failed removal must not block conclude or
+ * retire. The frontmatter reference is always cleared.
+ */
+export function reapQuestScratchDir(questDir, current) {
+    if (current && isReapableScratch(current)) {
+        try {
+            rmSync(current, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort cleanup: a wedged scratch dir must not stop the
+            // quest from concluding. The cleared frontmatter still drops
+            // the reference.
+        }
+    }
+    const path = questReadme(questDir);
+    if (existsSync(path)) {
+        withQuestLock(questDir, () => {
+            const parsed = parseQuestFrontMatter(readFileSync(path, "utf8"));
+            if (parsed)
+                writeScratchDir(path, parsed, undefined);
+        });
+    }
+    return Boolean(current);
+}