@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/quest/quest-doc.js

@@ -0,0 +1,239 @@
+/**
+ * Quest document model: parse a quest README into its
+ * structured projections.
+ *
+ * What we extract:
+ *
+ * - Front-matter (delegated to frontmatter.ts).
+ * - Title: first H1 of the body.
+ * - Section snippets: first paragraph of Summary and
+ *   Purpose, recent Journey entries, Cast bullets.
+ * - Milestone checkboxes: total and done count.
+ * - Inline references: bare quest/document IDs and any
+ *   text the registered ref types match.
+ *
+ * We do not try to make the parser idempotent over the
+ * body. Writers regenerate the structured sections; free
+ * prose is preserved by mutating the doc's `body` string
+ * directly.
+ */
+import { parseAllRefs } from "../../refs/index.js";
+import { parseQuestFrontMatter } from "./frontmatter.js";
+import { findIds, findIdsWithRelation } from "./id.js";
+const SECTION_HEADERS = {
+    summary: /^##\s+(?:[\u{1F300}-\u{1FFFF}]\s+)?Summary\s*$/u,
+    purpose: /^##\s+(?:[\u{1F300}-\u{1FFFF}]\s+)?Purpose\s*$/u,
+    cast: /^##\s+(?:[\u{1F300}-\u{1FFFF}]\s+)?Cast\s*$/u,
+    journey: /^##\s+(?:[\u{1F300}-\u{1FFFF}]\s+)?Journey\s*$/u,
+    milestones: /^##\s+(?:[\u{1F300}-\u{1FFFF}]\s+)?Milestones\s*$/u,
+    spirit: /^##\s+(?:[\u{1F300}-\u{1FFFF}]\s+)?Spirit\s*$/u,
+    outcomes: /^##\s+(?:[\u{1F300}-\u{1FFFF}]\s+)?Outcomes\s*$/u,
+    context: /^##\s+(?:[\u{1F300}-\u{1FFFF}]\s+)?Context\s*$/u,
+};
+const ANY_H2 = /^##\s+/;
+/** Parse a quest README and return the structured doc. */
+export function parseQuestDoc(text) {
+    const parsed = parseQuestFrontMatter(text);
+    if (!parsed)
+        return undefined;
+    return {
+        frontMatter: parsed.frontMatter,
+        body: parsed.body,
+        title: extractTitle(parsed.body),
+    };
+}
+/** Extract the first H1 from a body. */
+export function extractTitle(body) {
+    const match = /^#\s+(.+)$/m.exec(body);
+    return match ? match[1].trim() : undefined;
+}
+/**
+ * Extract the lines of a named section from a body. Returns
+ * the lines between the matching `## Section` header and
+ * the next `## ` header (or end of body). The header line
+ * itself is excluded.
+ */
+export function extractSection(body, header) {
+    const headerRegex = SECTION_HEADERS[header];
+    const lines = body.split("\n");
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (headerRegex.test(lines[i])) {
+            start = i + 1;
+            break;
+        }
+    }
+    if (start === -1)
+        return [];
+    let end = lines.length;
+    for (let i = start; i < lines.length; i++) {
+        if (ANY_H2.test(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    return lines.slice(start, end);
+}
+/** First paragraph (until blank line) of a section. */
+export function extractSectionParagraph(body, header) {
+    const sectionLines = extractSection(body, header);
+    const paragraph = [];
+    for (const line of sectionLines) {
+        if (line.trim() === "") {
+            if (paragraph.length > 0)
+                break;
+            continue;
+        }
+        paragraph.push(line);
+    }
+    return paragraph.length > 0 ? paragraph.join("\n").trim() : undefined;
+}
+/**
+ * A cast subject that's purely a scaffold placeholder, not
+ * a real person. The scaffold writes
+ * `- **owner**: _name or @handle_` into every fresh quest
+ * README; reading that bullet as a real cast entry made
+ * `who` and `show` echo the placeholder back to the user.
+ * We strip italic and bold delimiters then match the
+ * stripped form against a small set of known sentinels.
+ */
+function isCastPlaceholder(subject) {
+    const stripped = subject
+        .trim()
+        .replace(/^[*_]+/, "")
+        .replace(/[*_]+$/, "")
+        .trim()
+        .toLowerCase();
+    if (stripped.length === 0)
+        return true;
+    return (stripped === "name or @handle" ||
+        stripped === "name" ||
+        stripped === "@handle");
+}
+/**
+ * Parse the Cast section's role-prefix bullets. Skips
+ * scaffold placeholder subjects so an unedited template
+ * doesn't surface as a real cast entry.
+ */
+export function extractCast(body) {
+    const lines = extractSection(body, "cast");
+    const bullets = [];
+    const bulletRegex = /^-\s+\*\*([\w-]+)\*\*:\s*(.+)$/;
+    for (const line of lines) {
+        const m = bulletRegex.exec(line.trim());
+        if (!m)
+            continue;
+        const role = m[1].toLowerCase();
+        const rest = m[2].trim();
+        // The subject is the leading person token (a handle
+        // like @joel.gerber or a name like Joel Gerber).
+        // Names can be multi-word; we stop at the first
+        // sentence break (period followed by a space or
+        // end-of-string) or a comma.
+        let subjectEnd = rest.length;
+        const sentenceBreak = /\.(?:\s|$)/.exec(rest);
+        if (sentenceBreak)
+            subjectEnd = sentenceBreak.index;
+        const commaBreak = rest.indexOf(",");
+        if (commaBreak >= 0 && commaBreak < subjectEnd)
+            subjectEnd = commaBreak;
+        const subject = rest.slice(0, subjectEnd).trim();
+        if (isCastPlaceholder(subject))
+            continue;
+        const prose = rest
+            .slice(subjectEnd)
+            .replace(/^[.\s,]+/, "")
+            .trim();
+        bullets.push({ role, subject, prose });
+    }
+    return bullets;
+}
+/** Parse the Journey section's dated entries. */
+export function extractJourney(body) {
+    const lines = extractSection(body, "journey");
+    const entries = [];
+    const dateRegex = /^-\s+\*\*(\d{4}-\d{2}-\d{2})\*\*\s*:\s*(.*)$/;
+    const continuationRegex = /^\s+/;
+    let current;
+    for (const line of lines) {
+        const m = dateRegex.exec(line);
+        if (m) {
+            if (current)
+                entries.push(current);
+            current = { date: m[1], prose: m[2].trim() };
+            continue;
+        }
+        if (current && (continuationRegex.test(line) || line.trim() === "")) {
+            if (line.trim())
+                current.prose += `\n${line.trim()}`;
+        }
+    }
+    if (current)
+        entries.push(current);
+    return entries;
+}
+/** Count Milestones section checkboxes. */
+export function milestoneProgress(body) {
+    const section = extractSection(body, "milestones").join("\n");
+    const rx = /^\s*-\s+\[([ xX])\]/gm;
+    let total = 0;
+    let done = 0;
+    for (let m = rx.exec(section); m !== null; m = rx.exec(section)) {
+        total++;
+        if (m[1].toLowerCase() === "x")
+            done++;
+    }
+    return { total, done };
+}
+/**
+ * Count every `- [ ]` / `- [x]` checkbox in the body,
+ * regardless of which section holds it. Returns a count
+ * pair plus the prose of the first unchecked entry so the
+ * widget can render "5/33 → do the next thing" without
+ * re-parsing the body on every paint.
+ *
+ * The plan, research, brief and report templates all use
+ * different section names for their work list. Walking
+ * the whole body makes one counter serve all four kinds
+ * without coupling to a template detail.
+ */
+export function checkboxProgress(body) {
+    const rx = /^\s*-\s+\[([ xX])\]\s*(.*?)\s*$/gm;
+    let total = 0;
+    let done = 0;
+    let currentItem;
+    for (let m = rx.exec(body); m !== null; m = rx.exec(body)) {
+        total++;
+        const isDone = m[1].toLowerCase() === "x";
+        if (isDone) {
+            done++;
+            continue;
+        }
+        if (currentItem === undefined) {
+            currentItem = m[2] ?? "";
+        }
+    }
+    return currentItem === undefined
+        ? { total, done }
+        : { total, done, currentItem };
+}
+export function extractMentions(body) {
+    const idMentions = findIdsWithRelation(body);
+    return {
+        ids: findIds(body),
+        idMentions,
+        refs: parseAllRefs(body),
+    };
+}
+export function projectQuestForShow(doc) {
+    return {
+        frontMatter: doc.frontMatter,
+        title: doc.title,
+        summary: extractSectionParagraph(doc.body, "summary"),
+        purpose: extractSectionParagraph(doc.body, "purpose"),
+        cast: extractCast(doc.body),
+        journey: extractJourney(doc.body),
+        milestones: milestoneProgress(doc.body),
+        mentions: extractMentions(doc.body),
+    };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Pure rank-reordering math for sibling quests.
+ *
+ * A "sibling set" is the list of quests that share a
+ * parent and a priority bucket. Each one carries a `rank`
+ * integer; lower is more important. The functions here
+ * take the current ordering and return the new ordering;
+ * the extension does the disk writes.
+ *
+ * All functions produce a contiguous `1..N` numbering on
+ * output, regardless of the input numbering. This means a
+ * `bump` that succeeds shifts the rest of the bucket only
+ * when ranks were already contiguous; otherwise it acts as
+ * a renumber side-effect, which is what we want, since the
+ * bucket stays clean.
+ */
+export interface RankEntry {
+    id: string;
+    rank: number;
+}
+/**
+ * The next free rank for a sibling set: one past the highest
+ * existing rank, or 1 when the set is empty. Appends a new quest to
+ * the end of its group so it never collides with an existing rank.
+ */
+export declare function nextRank(ranks: number[]): number;
+/** Sort by rank ascending; stable on ties via the id. */
+export declare function sortByRank<T extends RankEntry>(entries: T[]): T[];
+/** Assign contiguous 1..N ranks in current order. */
+export declare function renumber<T extends RankEntry>(entries: T[]): T[];
+/** Move `id` to the top of the bucket. */
+export declare function top<T extends RankEntry>(entries: T[], id: string): T[];
+/** Move `id` to the bottom of the bucket. */
+export declare function bottom<T extends RankEntry>(entries: T[], id: string): T[];
+/** Swap `id` with the entry above it (move it up by one). */
+export declare function bump<T extends RankEntry>(entries: T[], id: string): T[];
+/** Swap `id` with the entry below it (move it down by one). */
+export declare function sink<T extends RankEntry>(entries: T[], id: string): T[];
+/** Place `id` immediately before `targetId`. */
+export declare function before<T extends RankEntry>(entries: T[], id: string, targetId: string): T[];
+/** Place `id` immediately after `targetId`. */
+export declare function after<T extends RankEntry>(entries: T[], id: string, targetId: string): T[];
+/** Diff two RankEntry lists: which entries changed rank? */
+export declare function diffRanks<T extends RankEntry>(before: T[], after: T[]): {
+    id: string;
+    from: number;
+    to: number;
+}[];

package/dist/internal/quest/ranking.js

@@ -0,0 +1,114 @@
+/**
+ * Pure rank-reordering math for sibling quests.
+ *
+ * A "sibling set" is the list of quests that share a
+ * parent and a priority bucket. Each one carries a `rank`
+ * integer; lower is more important. The functions here
+ * take the current ordering and return the new ordering;
+ * the extension does the disk writes.
+ *
+ * All functions produce a contiguous `1..N` numbering on
+ * output, regardless of the input numbering. This means a
+ * `bump` that succeeds shifts the rest of the bucket only
+ * when ranks were already contiguous; otherwise it acts as
+ * a renumber side-effect, which is what we want, since the
+ * bucket stays clean.
+ */
+/**
+ * The next free rank for a sibling set: one past the highest
+ * existing rank, or 1 when the set is empty. Appends a new quest to
+ * the end of its group so it never collides with an existing rank.
+ */
+export function nextRank(ranks) {
+    return ranks.length > 0 ? Math.max(...ranks) + 1 : 1;
+}
+/** Sort by rank ascending; stable on ties via the id. */
+export function sortByRank(entries) {
+    return [...entries].sort((a, b) => {
+        if (a.rank !== b.rank)
+            return a.rank - b.rank;
+        return a.id.localeCompare(b.id);
+    });
+}
+/** Assign contiguous 1..N ranks in current order. */
+export function renumber(entries) {
+    const sorted = sortByRank(entries);
+    return sorted.map((e, i) => ({ ...e, rank: i + 1 }));
+}
+function indexOf(entries, id) {
+    return entries.findIndex((e) => e.id === id);
+}
+function move(entries, from, to) {
+    const arr = [...entries];
+    const [moved] = arr.splice(from, 1);
+    arr.splice(to, 0, moved);
+    return arr.map((e, i) => ({ ...e, rank: i + 1 }));
+}
+/** Move `id` to the top of the bucket. */
+export function top(entries, id) {
+    const sorted = sortByRank(entries);
+    const i = indexOf(sorted, id);
+    if (i < 0)
+        return renumber(entries);
+    return move(sorted, i, 0);
+}
+/** Move `id` to the bottom of the bucket. */
+export function bottom(entries, id) {
+    const sorted = sortByRank(entries);
+    const i = indexOf(sorted, id);
+    if (i < 0)
+        return renumber(entries);
+    return move(sorted, i, sorted.length - 1);
+}
+/** Swap `id` with the entry above it (move it up by one). */
+export function bump(entries, id) {
+    const sorted = sortByRank(entries);
+    const i = indexOf(sorted, id);
+    if (i <= 0)
+        return renumber(entries);
+    return move(sorted, i, i - 1);
+}
+/** Swap `id` with the entry below it (move it down by one). */
+export function sink(entries, id) {
+    const sorted = sortByRank(entries);
+    const i = indexOf(sorted, id);
+    if (i < 0 || i >= sorted.length - 1)
+        return renumber(entries);
+    return move(sorted, i, i + 1);
+}
+/** Place `id` immediately before `targetId`. */
+export function before(entries, id, targetId) {
+    if (id === targetId)
+        return renumber(entries);
+    const sorted = sortByRank(entries);
+    const from = indexOf(sorted, id);
+    const target = indexOf(sorted, targetId);
+    if (from < 0 || target < 0)
+        return renumber(entries);
+    const adjustedTarget = from < target ? target - 1 : target;
+    return move(sorted, from, adjustedTarget);
+}
+/** Place `id` immediately after `targetId`. */
+export function after(entries, id, targetId) {
+    if (id === targetId)
+        return renumber(entries);
+    const sorted = sortByRank(entries);
+    const from = indexOf(sorted, id);
+    const target = indexOf(sorted, targetId);
+    if (from < 0 || target < 0)
+        return renumber(entries);
+    const adjustedTarget = from <= target ? target : target + 1;
+    return move(sorted, from, adjustedTarget);
+}
+/** Diff two RankEntry lists: which entries changed rank? */
+export function diffRanks(before, after) {
+    const beforeMap = new Map(before.map((e) => [e.id, e.rank]));
+    const out = [];
+    for (const entry of after) {
+        const prior = beforeMap.get(entry.id);
+        if (prior === undefined || prior !== entry.rank) {
+            out.push({ id: entry.id, from: prior ?? Number.NaN, to: entry.rank });
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Reopening resolvers for a quest: where to land and which session
+ * to resume.
+ *
+ * Both functions are pure given an existence predicate, so the
+ * spawn verb can wire real filesystem checks while tests inject a
+ * predicate. The point is that reopening a quest drops you back
+ * into the work: a real directory and, when there is one, the live
+ * session that was driving it.
+ */
+import type { QuestTree } from "../../quest/types.js";
+import type { SessionView } from "./session-liveness.js";
+/** The resolved working directory and how it was chosen. */
+export interface ResolvedCwd {
+    cwd: string;
+    source: "tree" | "session" | "repoRoot" | "questDir";
+    /** True when a recorded candidate was missing and we fell through. */
+    healed?: boolean;
+}
+/**
+ * Resolve the working directory to reopen a quest in. Preference
+ * order: an existing tree path (newest first), then the most-recent
+ * session's cwd, then a tree repoRoot, then the quest dir. A
+ * recorded path that no longer exists is skipped and the result is
+ * flagged as healed so the caller can offer to rewrite the record.
+ */
+export declare function resolveSpawnCwd(opts: {
+    questDir: string;
+    trees: QuestTree[];
+    sessions: SessionView[];
+    exists?: (p: string) => boolean;
+}): ResolvedCwd;
+/**
+ * Choose the session to resume. A live session wins: one live
+ * session resumes outright, several live ones are ambiguous
+ * (genuinely concurrent work) so the caller can ask which. With
+ * no live session, fall back to the most-recent idle one, since
+ * reopening yesterday's work is the common case, and staleness is
+ * surfaced, not refused. Only dead (no log) and detached sessions
+ * are excluded, so undefined means nothing is resumable.
+ */
+export declare function pickResumeSession(sessions: SessionView[]): {
+    id: string;
+} | {
+    ambiguous: SessionView[];
+} | undefined;
+/** A session projected for display in the `show` view. */
+export interface SessionSummary {
+    id: string;
+    name?: string;
+    cwd?: string;
+    liveness: SessionView["liveness"];
+    lastActivity?: string;
+    /** True for the one session a reopen would resume. */
+    resumeTarget: boolean;
+}
+/**
+ * Project a quest's attached sessions for the `show` view. Every
+ * attached session is reported, since show reflects the frontmatter
+ * honestly, and removing no-log phantoms is the prune verb's job,
+ * not this view's. Sessions are ordered newest-activity first, and
+ * the single session a reopen would land on (per pickResumeSession)
+ * is flagged so the reader can see what `spawn` will resume.
+ */
+export declare function summariseSessions(views: SessionView[]): SessionSummary[];

package/dist/internal/quest/reopen.js

@@ -0,0 +1,113 @@
+/**
+ * Reopening resolvers for a quest: where to land and which session
+ * to resume.
+ *
+ * Both functions are pure given an existence predicate, so the
+ * spawn verb can wire real filesystem checks while tests inject a
+ * predicate. The point is that reopening a quest drops you back
+ * into the work: a real directory and, when there is one, the live
+ * session that was driving it.
+ */
+import { existsSync } from "node:fs";
+/**
+ * Resolve the working directory to reopen a quest in. Preference
+ * order: an existing tree path (newest first), then the most-recent
+ * session's cwd, then a tree repoRoot, then the quest dir. A
+ * recorded path that no longer exists is skipped and the result is
+ * flagged as healed so the caller can offer to rewrite the record.
+ */
+export function resolveSpawnCwd(opts) {
+    const exists = opts.exists ?? existsSync;
+    let healed = false;
+    const markMissing = () => {
+        healed = true;
+    };
+    // Newest tree first: the trees array is appended to, so the
+    // last entry is the most recently added.
+    const trees = [...opts.trees].reverse();
+    for (const tree of trees) {
+        if (exists(tree.path)) {
+            return { cwd: tree.path, source: "tree", ...(healed ? { healed } : {}) };
+        }
+        markMissing();
+    }
+    // Most-recent session cwd next. A dead session's cwd is
+    // not a signal that work is happening there, so skip it.
+    const sessions = [...opts.sessions].sort(byActivityDesc);
+    for (const session of sessions) {
+        if (!session.cwd || session.liveness === "dead")
+            continue;
+        if (exists(session.cwd)) {
+            return {
+                cwd: session.cwd,
+                source: "session",
+                ...(healed ? { healed } : {}),
+            };
+        }
+        markMissing();
+    }
+    // A tree's origin repo root, newest first.
+    for (const tree of trees) {
+        if (tree.repoRoot && exists(tree.repoRoot)) {
+            return {
+                cwd: tree.repoRoot,
+                source: "repoRoot",
+                ...(healed ? { healed } : {}),
+            };
+        }
+    }
+    return {
+        cwd: opts.questDir,
+        source: "questDir",
+        ...(healed ? { healed } : {}),
+    };
+}
+/**
+ * Choose the session to resume. A live session wins: one live
+ * session resumes outright, several live ones are ambiguous
+ * (genuinely concurrent work) so the caller can ask which. With
+ * no live session, fall back to the most-recent idle one, since
+ * reopening yesterday's work is the common case, and staleness is
+ * surfaced, not refused. Only dead (no log) and detached sessions
+ * are excluded, so undefined means nothing is resumable.
+ */
+export function pickResumeSession(sessions) {
+    const byLiveness = (want) => sessions.filter((s) => s.liveness === want).sort(byActivityDesc);
+    const live = byLiveness("live");
+    if (live.length === 1)
+        return { id: live[0].id };
+    if (live.length > 1)
+        return { ambiguous: live };
+    // No live session: resume the most-recent idle one. Idle is
+    // stale, not concurrent, so several idle sessions are never
+    // ambiguous, and the newest is the one you left the work in.
+    const idle = byLiveness("idle");
+    if (idle.length > 0)
+        return { id: idle[0].id };
+    return undefined;
+}
+/**
+ * Project a quest's attached sessions for the `show` view. Every
+ * attached session is reported, since show reflects the frontmatter
+ * honestly, and removing no-log phantoms is the prune verb's job,
+ * not this view's. Sessions are ordered newest-activity first, and
+ * the single session a reopen would land on (per pickResumeSession)
+ * is flagged so the reader can see what `spawn` will resume.
+ */
+export function summariseSessions(views) {
+    const resume = pickResumeSession(views);
+    const targetId = resume && "id" in resume ? resume.id : undefined;
+    return [...views].sort(byActivityDesc).map((v) => ({
+        id: v.id,
+        ...(v.name ? { name: v.name } : {}),
+        ...(v.cwd ? { cwd: v.cwd } : {}),
+        liveness: v.liveness,
+        ...(v.lastActivity ? { lastActivity: v.lastActivity } : {}),
+        resumeTarget: v.id === targetId,
+    }));
+}
+function byActivityDesc(a, b) {
+    const at = a.lastActivity ? Date.parse(a.lastActivity) : 0;
+    const bt = b.lastActivity ? Date.parse(b.lastActivity) : 0;
+    return bt - at;
+}

package/dist/internal/quest/resolve-cwd.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 type { QuestIndex } from "./discovery.js";
+/**
+ * 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 declare function questIdForCwd(index: QuestIndex, cwd: string): string | undefined;