@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/quest/mentions.js

@@ -0,0 +1,70 @@
+/**
+ * Reverse-mention index: for each quest in the index, find
+ * every other quest whose body or documents mention it.
+ *
+ * Two kinds of mentions:
+ *
+ * - Bare IDs in prose: `QEST-...`, `PLAN-...`, etc.
+ * - Refs: anything the registered ref types extract.
+ *
+ * For Echoes rendering on `quest show`, we care about
+ * inbound mentions: "who has mentioned QEST-X". The reverse
+ * map is keyed by the target id (or ref canonical) and
+ * values are the source quests.
+ */
+import { extractMentions } from "./quest-doc.js";
+const SNIPPET_RADIUS = 80;
+function findSnippet(body, needle) {
+    const idx = body.indexOf(needle);
+    if (idx < 0)
+        return "";
+    const start = Math.max(0, idx - SNIPPET_RADIUS);
+    const end = Math.min(body.length, idx + needle.length + SNIPPET_RADIUS);
+    const raw = body.slice(start, end).replace(/\s+/g, " ").trim();
+    const prefix = start > 0 ? "..." : "";
+    const suffix = end < body.length ? "..." : "";
+    return `${prefix}${raw}${suffix}`;
+}
+/**
+ * Build a reverse-mention index over every quest in the
+ * input. Each quest contributes both its README body and
+ * its documents' bodies to the mention pool.
+ */
+export function buildMentionIndex(index) {
+    const byId = new Map();
+    const byRef = new Map();
+    const push = (map, key, edge) => {
+        const list = map.get(key) ?? [];
+        list.push(edge);
+        map.set(key, list);
+    };
+    for (const [questId, entry] of index.quests) {
+        const bodies = [entry.doc.body];
+        for (const docEntry of entry.documents)
+            bodies.push(docEntry.doc.body);
+        const combined = bodies.join("\n\n");
+        const mentions = extractMentions(combined);
+        for (const idMention of mentions.idMentions) {
+            if (idMention.id === questId)
+                continue;
+            push(byId, idMention.id, {
+                from: questId,
+                snippet: findSnippet(combined, idMention.id),
+                relation: idMention.relation,
+            });
+        }
+        for (const ref of mentions.refs) {
+            const key = `${ref.type}:${ref.value}`;
+            push(byRef, key, {
+                from: questId,
+                snippet: findSnippet(combined, ref.value),
+                relation: "reference",
+            });
+        }
+    }
+    return { byId, byRef };
+}
+/** Convenience: lookup inbound mentions for one target quest id. */
+export function mentionsOf(index, targetId) {
+    return index.byId.get(targetId) ?? [];
+}

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

@@ -0,0 +1,38 @@
+/**
+ * The single validated, journalled mutation entry point for a
+ * quest README.
+ *
+ * Every field change on a quest should flow through here. The
+ * layer reads the README under the per-quest lock, applies a pure
+ * transform, and refuses to write a result the strict parser
+ * cannot read back, so an out-of-vocabulary value is blocked at
+ * write time instead of landing on disk as an invisible record.
+ * It reports the per-field diff and, when an operation name is
+ * given, appends that diff to the structural journal so the change
+ * is reversible.
+ */
+import type { QuestFrontMatter } from "../../quest/types.js";
+import { type JournalChange } from "./structural-journal.js";
+/** Outcome of a mutation attempt. */
+export type MutateResult = {
+    ok: true;
+    fm: QuestFrontMatter;
+    changes: JournalChange[];
+} | {
+    ok: false;
+    guidance: string;
+};
+interface MutateOptions {
+    /** Journal the diff under this operation name. Omit to skip. */
+    op?: string;
+    /** Journal location; defaults to the quest directory's parent. */
+    questsRoot?: string;
+    /** Stamp `updated` with today's date. Defaults to true. */
+    stampUpdated?: boolean;
+}
+/**
+ * Apply a validated, locked write to a quest README, reporting the
+ * per-field diff and optionally journalling it.
+ */
+export declare function mutateQuestFrontMatter(questDir: string, transform: (fm: QuestFrontMatter) => QuestFrontMatter | undefined, opts?: MutateOptions): MutateResult;
+export {};

package/dist/internal/quest/mutate.js

@@ -0,0 +1,83 @@
+/**
+ * The single validated, journalled mutation entry point for a
+ * quest README.
+ *
+ * Every field change on a quest should flow through here. The
+ * layer reads the README under the per-quest lock, applies a pure
+ * transform, and refuses to write a result the strict parser
+ * cannot read back, so an out-of-vocabulary value is blocked at
+ * write time instead of landing on disk as an invisible record.
+ * It reports the per-field diff and, when an operation name is
+ * given, appends that diff to the structural journal so the change
+ * is reversible.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { nowYmd } from "./dates.js";
+import { lensForField, reversibleFields } from "./fields.js";
+import { parseQuestFrontMatter, serializeReadable } from "./frontmatter.js";
+import { atomicWriteFile, withQuestLock } from "./io.js";
+import { recordStructuralOp, } from "./structural-journal.js";
+function diffTracked(id, before, after) {
+    const changes = [];
+    // The fields worth journalling are exactly the ones undo can put
+    // back, so both read the one lens table rather than keeping a list
+    // here that has to be remembered to match.
+    for (const field of reversibleFields()) {
+        const lens = lensForField(field);
+        if (!lens)
+            continue;
+        const old = lens.read(before);
+        const next = lens.read(after);
+        if (old !== next)
+            changes.push({ id, field, old, new: next });
+    }
+    return changes;
+}
+/**
+ * Apply a validated, locked write to a quest README, reporting the
+ * per-field diff and optionally journalling it.
+ */
+export function mutateQuestFrontMatter(questDir, transform, opts = {}) {
+    const path = join(questDir, "README.md");
+    return withQuestLock(questDir, () => {
+        let text;
+        try {
+            text = readFileSync(path, "utf8");
+        }
+        catch (err) {
+            return {
+                ok: false,
+                guidance: `Cannot read ${path}: ${err.message}`,
+            };
+        }
+        const parsed = parseQuestFrontMatter(text);
+        if (!parsed) {
+            return {
+                ok: false,
+                guidance: `Quest README ${path} has invalid frontmatter.`,
+            };
+        }
+        const next = transform(parsed.frontMatter);
+        if (!next) {
+            return { ok: true, fm: parsed.frontMatter, changes: [] };
+        }
+        const stamped = opts.stampUpdated === false ? next : { ...next, updated: nowYmd() };
+        // Write-time validation: refuse a mutation that would produce a
+        // record the strict parser cannot read back, so an out-of-vocab
+        // value is blocked instead of written to invisible drift. Shared
+        // with every other quest writer, which is the point of it living
+        // beside the parser rather than here.
+        const serialized = serializeReadable(stamped, parsed.body);
+        if (!serialized.ok) {
+            return { ok: false, guidance: serialized.reason };
+        }
+        const outText = serialized.text;
+        const changes = diffTracked(parsed.frontMatter.id, parsed.frontMatter, stamped);
+        atomicWriteFile(path, outText);
+        if (opts.op && changes.length > 0) {
+            recordStructuralOp(opts.questsRoot ?? dirname(questDir), opts.op, changes);
+        }
+        return { ok: true, fm: stamped, changes };
+    });
+}

package/dist/internal/quest/process-liveness.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The process-liveness floor: classify a recorded pi process by
+ * whether it is still running, using an OS-derived start token to
+ * survive pid reuse. This is the terminal-agnostic layer under the
+ * terminal-driver liveness capability; a session with no terminal
+ * identity still gets an honest answer from its process alone.
+ *
+ * The OS inspection is injected so the branching logic stays pure
+ * and testable; the platform readers live in the caller.
+ */
+/** Stable identity of a recorded pi process. */
+export interface ProcessIdentity {
+    /** Host the process was observed on; a remote host is unprobeable. */
+    hostId: string;
+    /** OS process id. */
+    pid: number;
+    /**
+     * OS-derived process-start token (creation time or equivalent).
+     * Distinguishes the original process from a later pid reuse.
+     */
+    startToken: string;
+    /**
+     * Identifier of the boot the process was recorded under. A reboot
+     * invalidates every pid on the host at once, so a record from an
+     * earlier boot is dead whatever the pid now holds. Optional: a
+     * record written before this was captured, or on a host with no
+     * readable token, falls through to the pid inspection.
+     */
+    bootToken?: string;
+}
+/** What an OS inspection of a pid found. */
+export type ProcessInspection = {
+    kind: "alive";
+    startToken: string;
+} | {
+    kind: "gone";
+} | {
+    kind: "unknown";
+};
+/** The floor's verdict for one recorded process. */
+export type ProcessProbe = "matching" | "gone" | "unknown";
+/** Dependencies for {@link probeProcess}: the local host and the OS reader. */
+export interface ProbeProcessDeps {
+    /** The reader's own host id, compared against the recorded host. */
+    localHostId: string;
+    /** Inspect a live pid on the local host. */
+    inspect: (pid: number) => ProcessInspection;
+    /**
+     * The boot the reader is running under. Optional, because a host
+     * with no readable token must not declare anything dead.
+     */
+    localBootToken?: string;
+}
+/**
+ * Map the observable facts of a `ps -o lstart=` lookup to an
+ * inspection. Only a clean non-zero exit that printed no diagnostic
+ * is `gone` (the pid holds no process); a diagnostic on stderr means
+ * `ps` rejected the query (an unsupported option on a minimal `ps`),
+ * and a lookup that never spawned is `unknown`, so an inability to
+ * probe is never read as death.
+ */
+export declare function interpretPsLookup(r: {
+    spawned: boolean;
+    exitStatus: number | null;
+    stdout: string;
+    stderr: string;
+}): ProcessInspection;
+/**
+ * Build a probeable process identity from a live inspection, or none
+ * when the start token could not be read. Recording an identity with
+ * a synthetic token would guarantee a later mismatch against a real
+ * ps reading and read the session dead, so an unreadable capture is
+ * left without a process identity and falls back to recency instead.
+ */
+export declare function identityFromInspection(hostId: string, pid: number, inspection: ProcessInspection): ProcessIdentity | undefined;
+/**
+ * Identity of the currently running pi process, for capture onto the
+ * session it is attached to. Undefined when the OS reader could not
+ * read a real start token: a session then carries no process identity
+ * and its liveness falls back to recency, rather than a synthetic
+ * token that a later probe would read as a dead mismatch.
+ */
+export declare function currentProcessIdentity(): ProcessIdentity | undefined;
+/**
+ * The identifier of the boot this process is running under, read once
+ * and remembered. Undefined on a host that publishes none, in which
+ * case no session is ever judged by boot.
+ */
+export declare function currentBootToken(): string | undefined;
+/** The always-on local floor: this host plus the OS start-token reader. */
+export declare function localProcessDeps(): ProbeProcessDeps;
+/**
+ * The current pi process's instance id, stable for the life of the
+ * process. Stored on a session at attach so a later shutdown detaches
+ * only when the same instance still owns it.
+ */
+export declare function currentInstanceId(): string;
+export declare function probeProcess(id: ProcessIdentity, deps: ProbeProcessDeps): ProcessProbe;

package/dist/internal/quest/process-liveness.js

@@ -0,0 +1,216 @@
+/**
+ * The process-liveness floor: classify a recorded pi process by
+ * whether it is still running, using an OS-derived start token to
+ * survive pid reuse. This is the terminal-agnostic layer under the
+ * terminal-driver liveness capability; a session with no terminal
+ * identity still gets an honest answer from its process alone.
+ *
+ * The OS inspection is injected so the branching logic stays pure
+ * and testable; the platform readers live in the caller.
+ */
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+/**
+ * Classify a recorded process. A recorded host that is not the local
+ * host is unknown (we cannot see it). Otherwise the OS inspection
+ * decides: no such pid is gone, a pid held by a process with a
+ * different start token is gone (reuse), a matching token is
+ * matching, and anything the inspection could not determine is
+ * unknown.
+ */
+/**
+ * Read a live pid's OS start token. Uses `ps -o lstart=`, present on
+ * macOS and Linux, which yields a stable per-process start timestamp
+ * that distinguishes a pid from a later reuse. A pid no process holds
+ * is gone; a missing `ps` or any other failure is unknown, so an
+ * inability to probe never reads as death.
+ */
+function readStartToken(pid) {
+    try {
+        const stdout = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8",
+        });
+        return interpretPsLookup({
+            spawned: true,
+            exitStatus: 0,
+            stdout,
+            stderr: "",
+        });
+    }
+    catch (error) {
+        return interpretPsLookup(psLookupFromError(error));
+    }
+}
+/** Read the observable facts of a failed `ps` run off the thrown error. */
+function psLookupFromError(error) {
+    const e = (error ?? {});
+    const exitStatus = typeof e.status === "number" ? e.status : null;
+    return {
+        // A numeric exit status means `ps` ran; no status means it never
+        // spawned (absent binary, unsupported platform).
+        spawned: exitStatus !== null,
+        exitStatus,
+        stdout: typeof e.stdout === "string" ? e.stdout : "",
+        stderr: typeof e.stderr === "string" ? e.stderr : "",
+    };
+}
+/**
+ * Map the observable facts of a `ps -o lstart=` lookup to an
+ * inspection. Only a clean non-zero exit that printed no diagnostic
+ * is `gone` (the pid holds no process); a diagnostic on stderr means
+ * `ps` rejected the query (an unsupported option on a minimal `ps`),
+ * and a lookup that never spawned is `unknown`, so an inability to
+ * probe is never read as death.
+ */
+export function interpretPsLookup(r) {
+    if (!r.spawned)
+        return { kind: "unknown" };
+    if (r.exitStatus === 0) {
+        const token = r.stdout.trim();
+        // A live pid always prints its start line on a zero exit. An
+        // empty zero-exit is anomalous, not a clean "no such pid" (that
+        // comes via a non-zero exit), so treat it as unknown rather than
+        // declaring death.
+        return token.length > 0
+            ? { kind: "alive", startToken: token }
+            : { kind: "unknown" };
+    }
+    // A non-zero exit is only "no such pid" when ps said nothing at
+    // all; any diagnostic, on either stream, means it could not answer
+    // the query, which is unknown rather than death.
+    const quiet = r.stdout.trim().length === 0 && r.stderr.trim().length === 0;
+    return quiet ? { kind: "gone" } : { kind: "unknown" };
+}
+/**
+ * Build a probeable process identity from a live inspection, or none
+ * when the start token could not be read. Recording an identity with
+ * a synthetic token would guarantee a later mismatch against a real
+ * ps reading and read the session dead, so an unreadable capture is
+ * left without a process identity and falls back to recency instead.
+ */
+export function identityFromInspection(hostId, pid, inspection) {
+    return inspection.kind === "alive"
+        ? { hostId, pid, startToken: inspection.startToken }
+        : undefined;
+}
+/**
+ * Identity of the currently running pi process, for capture onto the
+ * session it is attached to. Undefined when the OS reader could not
+ * read a real start token: a session then carries no process identity
+ * and its liveness falls back to recency, rather than a synthetic
+ * token that a later probe would read as a dead mismatch.
+ */
+export function currentProcessIdentity() {
+    const identity = identityFromInspection(hostname(), process.pid, readStartToken(process.pid));
+    if (!identity)
+        return undefined;
+    // Stamp the boot alongside the pid, so a later reader can retire
+    // this record wholesale after a reboot instead of asking the OS
+    // about a pid that means nothing any more.
+    const bootToken = currentBootToken();
+    return bootToken ? { ...identity, bootToken } : identity;
+}
+/**
+ * Whether the record is known to come from a different boot than the
+ * reader's. Both tokens have to be present to say so: a record
+ * written before boot tokens were captured, or a host with no
+ * readable token, is not evidence of death.
+ */
+function fromAnotherBoot(id, deps) {
+    return (id.bootToken !== undefined &&
+        deps.localBootToken !== undefined &&
+        id.bootToken !== deps.localBootToken);
+}
+/**
+ * Where Linux publishes a random identifier regenerated on each boot.
+ */
+const LINUX_BOOT_ID_PATH = "/proc/sys/kernel/random/boot_id";
+/**
+ * Read an identifier for the running boot, or undefined when the host
+ * offers none.
+ *
+ * Both platforms expose a uuid minted at boot rather than a
+ * timestamp: Linux in procfs, macOS as `kern.bootsessionuuid`. The
+ * neighbouring `kern.boottime` looks like the obvious source and is
+ * not one, because it is derived from the clock and shifts when NTP
+ * adjusts it. A token that drifts mid-boot would read every live
+ * session as dead, which is the one answer this module must never
+ * invent.
+ */
+function readBootToken() {
+    if (process.platform === "linux") {
+        try {
+            return nonEmpty(readFileSync(LINUX_BOOT_ID_PATH, "utf8"));
+        }
+        catch {
+            // No procfs (a container, an unusual mount): no token, so the
+            // probe falls through to inspecting the pid.
+            return undefined;
+        }
+    }
+    try {
+        return nonEmpty(execFileSync("sysctl", ["-n", "kern.bootsessionuuid"], {
+            encoding: "utf8",
+        }));
+    }
+    catch {
+        // No sysctl, or the key is absent on this platform: same again,
+        // no token rather than a guess.
+        return undefined;
+    }
+}
+/** Trim a reading, treating blank output as no reading at all. */
+function nonEmpty(raw) {
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/** Memoized boot token; a boot identifier cannot change under us. */
+let bootTokenCache;
+/**
+ * The identifier of the boot this process is running under, read once
+ * and remembered. Undefined on a host that publishes none, in which
+ * case no session is ever judged by boot.
+ */
+export function currentBootToken() {
+    bootTokenCache ??= { token: readBootToken() };
+    return bootTokenCache.token;
+}
+/** The always-on local floor: this host plus the OS start-token reader. */
+export function localProcessDeps() {
+    const localBootToken = currentBootToken();
+    return {
+        localHostId: hostname(),
+        inspect: readStartToken,
+        ...(localBootToken ? { localBootToken } : {}),
+    };
+}
+/** Id minted once per pi process, identifying which process holds a session lease. */
+const INSTANCE_ID = randomUUID();
+/**
+ * The current pi process's instance id, stable for the life of the
+ * process. Stored on a session at attach so a later shutdown detaches
+ * only when the same instance still owns it.
+ */
+export function currentInstanceId() {
+    return INSTANCE_ID;
+}
+export function probeProcess(id, deps) {
+    if (id.hostId !== deps.localHostId)
+        return "unknown";
+    // A pid outlives nothing across a reboot, so a record from an
+    // earlier boot is dead without asking the OS: whatever holds that
+    // pid now is a reuse, even when its start token happens to match.
+    if (fromAnotherBoot(id, deps))
+        return "gone";
+    const found = deps.inspect(id.pid);
+    switch (found.kind) {
+        case "gone":
+            return "gone";
+        case "unknown":
+            return "unknown";
+        case "alive":
+            return found.startToken === id.startToken ? "matching" : "gone";
+    }
+}

package/dist/internal/quest/quest-doc.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 type { CastEntry, JourneyEntry, QuestDoc, QuestFrontMatter } from "../../quest/types.js";
+import { type IdMention } from "./id.js";
+declare const SECTION_HEADERS: {
+    readonly summary: RegExp;
+    readonly purpose: RegExp;
+    readonly cast: RegExp;
+    readonly journey: RegExp;
+    readonly milestones: RegExp;
+    readonly spirit: RegExp;
+    readonly outcomes: RegExp;
+    readonly context: RegExp;
+};
+/** Parse a quest README and return the structured doc. */
+export declare function parseQuestDoc(text: string): QuestDoc | undefined;
+/** Extract the first H1 from a body. */
+export declare function extractTitle(body: string): string | 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 declare function extractSection(body: string, header: keyof typeof SECTION_HEADERS): string[];
+/** First paragraph (until blank line) of a section. */
+export declare function extractSectionParagraph(body: string, header: keyof typeof SECTION_HEADERS): string | undefined;
+/**
+ * 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 declare function extractCast(body: string): CastEntry[];
+/** Parse the Journey section's dated entries. */
+export declare function extractJourney(body: string): JourneyEntry[];
+/** Count Milestones section checkboxes. */
+export declare function milestoneProgress(body: string): {
+    total: number;
+    done: number;
+};
+/**
+ * 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 declare function checkboxProgress(body: string): {
+    total: number;
+    done: number;
+    currentItem?: string;
+};
+/**
+ * Pull every inline reference out of the body: bare quest
+ * IDs and any pattern recognised by a registered ref type.
+ *
+ * `ids` lists every ID found, in order of first appearance.
+ * `idMentions` adds the `→` sigil relation: an id
+ * preceded by `→` is marked `produced`; bare ids are
+ * marked `reference`. Consumers that don't care about the
+ * relation can keep using `ids`.
+ */
+export interface ExtractedMentions {
+    /** Quest, plan, research, brief or report IDs. */
+    ids: string[];
+    /** Same IDs, classified as produced-by or bare reference. */
+    idMentions: IdMention[];
+    /** Refs through the registered ref types. */
+    refs: Array<{
+        type: string;
+        value: string;
+    }>;
+}
+export declare function extractMentions(body: string): ExtractedMentions;
+/**
+ * Quick projection used by the `quest show` action. Combines
+ * the snippets the agent needs to synthesise a paragraph
+ * about a quest.
+ */
+export interface QuestShowProjection {
+    frontMatter: QuestFrontMatter;
+    title?: string;
+    summary?: string;
+    purpose?: string;
+    cast: CastEntry[];
+    journey: JourneyEntry[];
+    milestones: {
+        total: number;
+        done: number;
+    };
+    mentions: ExtractedMentions;
+}
+export declare function projectQuestForShow(doc: QuestDoc): QuestShowProjection;
+export {};