@jitsusama/agentic-harness.core 0.1.0

package/dist/quest/render-rows.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Plain-text row rendering for the listing-style query
+ * verbs (`list`, `find`, `who`, `links`, `tree`, `expand`).
+ *
+ * Two shapes:
+ *
+ * - Brief: one line per row, `{id} {kindGlyph} {statusGlyph} {title}`.
+ *   This is what the agent reads first and acts on. The
+ *   glyphs are picked so a quest and a sidequest are
+ *   distinguishable at a glance without colour.
+ * - Expanded: brief plus key front-matter (priority,
+ *   parent, updated), summary line, cast bullets, recent
+ *   journey entries and document list. What the user
+ *   wants when they need the whole picture without
+ *   leaving the tool.
+ *
+ * Plus a small pagination helper so every verb caps its
+ * brief output at the same default and tails with a
+ * single uniform "... and N more" hint.
+ */
+import type { QuestKind, QuestStatus } from "./index.js";
+/** The default cap on rows returned in brief mode. */
+export declare const DEFAULT_LISTING_LIMIT = 25;
+/** Smallest fields a brief row needs. */
+export interface QuestRowBrief {
+    id: string;
+    kind: QuestKind;
+    status: QuestStatus;
+    priority: string;
+    title: string | null;
+}
+/**
+ * Render one brief row as a single parsable line. The kind,
+ * status and priority are spelled out as `key=value` words
+ * rather than glyphs so the agent reads them without a legend;
+ * the glyph form lives in {@link renderRowGlyph} for the
+ * human-facing expanded view.
+ */
+export declare function renderRowBrief(row: QuestRowBrief): string;
+/** Render one row in the glyph form for the expanded human view. */
+export declare function renderRowGlyph(row: QuestRowBrief): string;
+/** A legend mapping each kind and status glyph to its word. */
+export declare function questGlyphLegend(): string;
+/** A document listed under a quest. */
+export interface RowDocument {
+    id: string;
+    stage: string;
+}
+/** A cast bullet, brief. */
+export interface RowCast {
+    role: string;
+    subject: string;
+}
+/** A journey entry, brief. */
+export interface RowJourney {
+    date: string;
+    prose: string;
+}
+/** All the fields the expanded row uses. */
+export interface QuestRowExpanded extends QuestRowBrief {
+    priority: string;
+    parent: string | null;
+    updated: string;
+    summary?: string;
+    cast?: RowCast[];
+    documents?: RowDocument[];
+    recentJourney?: RowJourney[];
+}
+/** Render one expanded row as a small block of lines. */
+export declare function renderRowExpanded(row: QuestRowExpanded): string;
+/** Pagination request. */
+export interface PaginationOpts {
+    limit?: number;
+    offset?: number;
+    defaultLimit?: number;
+}
+/** Pagination result, used to render the trailing hint. */
+export interface PaginationView<T> {
+    rows: T[];
+    total: number;
+    offset: number;
+    limit: number;
+    remaining: number;
+}
+/**
+ * Slice `items` according to `limit` and `offset`. Both
+ * default to gentle values: limit to `DEFAULT_LISTING_LIMIT`
+ * (or the caller's override) and offset to zero. Negative
+ * inputs are clamped.
+ */
+export declare function paginate<T>(items: T[], opts?: PaginationOpts): PaginationView<T>;
+/**
+ * A row in the listing payload that `renderResult` reads
+ * to paint the expanded view on Ctrl-O. Each row already
+ * carries every field `renderRowExpanded` needs, so the
+ * renderer does no further disk IO when toggling.
+ */
+export interface ListingFlatRow extends QuestRowExpanded {
+    /** Indent depth, used by tree-shaped listings. Flat
+     * listings leave this as 0. */
+    depth: number;
+}
+/**
+ * The structured payload a listing verb attaches to
+ * `result.details.listing`. `renderResult` reads this on
+ * Ctrl-O and reformats the rows into the expanded view
+ * without re-running discovery.
+ */
+export interface ListingDetails {
+    rows: ListingFlatRow[];
+    total: number;
+    offset: number;
+    limit: number;
+    remaining: number;
+}
+/**
+ * Render a listing as expanded blocks, one block per row,
+ * separated by blank lines. Tree-shaped listings indent
+ * each block by the row's `depth`. The trailing pagination
+ * hint comes from `renderListing` so the format matches
+ * the brief view.
+ */
+export declare function renderListingExpanded(details: ListingDetails): string;
+/**
+ * Join already-rendered row strings into one listing block,
+ * appending the "... and N more" tail when more rows exist
+ * past the current page.
+ *
+ * Empty-page output discriminates between the two reasons:
+ *
+ * - The whole set really is empty: returns `(no matches)`.
+ * - The user paged past the end of a non-empty set: returns
+ *   a hint about the total and a working offset to start
+ *   from. Without this, an agent paging through a list got
+ *   `(no matches)` on the trailing page and concluded
+ *   nothing was there.
+ */
+export declare function renderListing<T>(rendered: string[], view: PaginationView<T>): string;
+/**
+ * Defensive shape check for a listing payload. The
+ * `renderResult` callback runs inside pi's render loop,
+ * where a thrown error tanks the frame; trust the cast
+ * only after the shape clears.
+ */
+export declare function isListingDetails(value: unknown): value is ListingDetails;
+/**
+ * One-line preview of a listing result for the collapsed
+ * (default) tool widget. Shows the first brief row and a
+ * row-count suffix so the human can tell how much more
+ * is hidden before pressing Ctrl-O. The count combines
+ * the remaining rows on this page with whatever paging
+ * left behind, so a paged result reads honestly. Empty
+ * listings fall back to the rendered content, which
+ * already says `(no matches)` or `(no quests)`.
+ */
+export declare function collapseListingPreview(listing: ListingDetails, content: string): string;
+/**
+ * Collapse a multi-line, non-listing result (show, who, links) for the
+ * human TUI. Expanded or single-line content is returned whole; a
+ * multi-line result collapses to its first line plus a count of the
+ * hidden lines and an expand hint, so the reader knows the rich output
+ * is there and how to see it. This is the counterpart that keeps the
+ * human render and the agent result fed from one text, rather than
+ * silently dropping everything past the first line for the human.
+ */
+export declare function collapseText(content: string, expanded: boolean, expandHint: string): string;

package/dist/quest/render-rows.js

@@ -0,0 +1,214 @@
+/**
+ * Plain-text row rendering for the listing-style query
+ * verbs (`list`, `find`, `who`, `links`, `tree`, `expand`).
+ *
+ * Two shapes:
+ *
+ * - Brief: one line per row, `{id} {kindGlyph} {statusGlyph} {title}`.
+ *   This is what the agent reads first and acts on. The
+ *   glyphs are picked so a quest and a sidequest are
+ *   distinguishable at a glance without colour.
+ * - Expanded: brief plus key front-matter (priority,
+ *   parent, updated), summary line, cast bullets, recent
+ *   journey entries and document list. What the user
+ *   wants when they need the whole picture without
+ *   leaving the tool.
+ *
+ * Plus a small pagination helper so every verb caps its
+ * brief output at the same default and tails with a
+ * single uniform "... and N more" hint.
+ */
+import { count } from "../ui/count.js";
+const KIND_GLYPHS = {
+    quest: "\u25c6", // ◆
+    subquest: "\u25c8", // ◈
+    sidequest: "\u25c7", // ◇
+};
+const STATUS_GLYPHS = {
+    active: "\u25cb", // ○
+    paused: "\u25d0", // ◐
+    blocked: "\u2298", // ⊘
+    concluded: "\u25cf", // ●
+    retired: "\u2297", // ⊗
+};
+/** The default cap on rows returned in brief mode. */
+export const DEFAULT_LISTING_LIMIT = 25;
+/**
+ * Render one brief row as a single parsable line. The kind,
+ * status and priority are spelled out as `key=value` words
+ * rather than glyphs so the agent reads them without a legend;
+ * the glyph form lives in {@link renderRowGlyph} for the
+ * human-facing expanded view.
+ */
+export function renderRowBrief(row) {
+    const title = row.title ?? "(untitled)";
+    return `${row.id} kind=${row.kind} status=${row.status} priority=${row.priority} ${title}`;
+}
+/** Render one row in the glyph form for the expanded human view. */
+export function renderRowGlyph(row) {
+    const kindGlyph = KIND_GLYPHS[row.kind];
+    const statusGlyph = STATUS_GLYPHS[row.status];
+    const title = row.title ?? "(untitled)";
+    return `${row.id} ${kindGlyph} ${statusGlyph} ${title}`;
+}
+/** A legend mapping each kind and status glyph to its word. */
+export function questGlyphLegend() {
+    const kinds = Object.entries(KIND_GLYPHS)
+        .map(([word, glyph]) => `${glyph} ${word}`)
+        .join("  ");
+    const statuses = Object.entries(STATUS_GLYPHS)
+        .map(([word, glyph]) => `${glyph} ${word}`)
+        .join("  ");
+    return `Legend -- kind: ${kinds}; status: ${statuses}`;
+}
+/** Render one expanded row as a small block of lines. */
+export function renderRowExpanded(row) {
+    const lines = [renderRowGlyph(row)];
+    const parent = row.parent ?? "none";
+    // Sparse rows (e.g. the synthetic (orphans) tree node)
+    // arrive with an empty updated; suppress the dangling
+    // `updated:` field rather than print an empty value.
+    const metaParts = [`priority: ${row.priority}`, `parent: ${parent}`];
+    if (row.updated)
+        metaParts.push(`updated: ${row.updated}`);
+    lines.push(`  ${metaParts.join("  ")}`);
+    if (row.summary)
+        lines.push(`  summary: ${row.summary}`);
+    if (row.cast && row.cast.length > 0) {
+        const cast = row.cast.map((c) => `${c.subject} (${c.role})`).join(", ");
+        lines.push(`  cast: ${cast}`);
+    }
+    if (row.documents && row.documents.length > 0) {
+        const docs = row.documents.map((d) => `${d.id} (${d.stage})`).join(", ");
+        lines.push(`  docs: ${docs}`);
+    }
+    if (row.recentJourney && row.recentJourney.length > 0) {
+        lines.push("  recent journey:");
+        for (const j of row.recentJourney) {
+            lines.push(`    ${j.date}: ${j.prose}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Slice `items` according to `limit` and `offset`. Both
+ * default to gentle values: limit to `DEFAULT_LISTING_LIMIT`
+ * (or the caller's override) and offset to zero. Negative
+ * inputs are clamped.
+ */
+export function paginate(items, opts = {}) {
+    const limit = Math.max(1, opts.limit ?? opts.defaultLimit ?? DEFAULT_LISTING_LIMIT);
+    const offset = Math.max(0, opts.offset ?? 0);
+    const rows = items.slice(offset, offset + limit);
+    const remaining = Math.max(0, items.length - offset - rows.length);
+    return { rows, total: items.length, offset, limit, remaining };
+}
+/**
+ * Render a listing as expanded blocks, one block per row,
+ * separated by blank lines. Tree-shaped listings indent
+ * each block by the row's `depth`. The trailing pagination
+ * hint comes from `renderListing` so the format matches
+ * the brief view.
+ */
+export function renderListingExpanded(details) {
+    if (details.rows.length === 0) {
+        if (details.total === 0)
+            return "(no matches)";
+        return `(empty page; ${details.total} total, try offset 0)`;
+    }
+    const blocks = details.rows.map((row) => {
+        const block = renderRowExpanded(row);
+        if (row.depth <= 0)
+            return block;
+        const indent = "  ".repeat(row.depth);
+        return block
+            .split("\n")
+            .map((line) => `${indent}${line}`)
+            .join("\n");
+    });
+    const body = blocks.join("\n\n");
+    const legend = questGlyphLegend();
+    if (details.remaining === 0)
+        return `${legend}\n\n${body}`;
+    const nextOffset = details.offset + details.rows.length;
+    return `${legend}\n\n${body}\n\n... and ${details.remaining} more (offset ${nextOffset} to continue)`;
+}
+/**
+ * Join already-rendered row strings into one listing block,
+ * appending the "... and N more" tail when more rows exist
+ * past the current page.
+ *
+ * Empty-page output discriminates between the two reasons:
+ *
+ * - The whole set really is empty: returns `(no matches)`.
+ * - The user paged past the end of a non-empty set: returns
+ *   a hint about the total and a working offset to start
+ *   from. Without this, an agent paging through a list got
+ *   `(no matches)` on the trailing page and concluded
+ *   nothing was there.
+ */
+export function renderListing(rendered, view) {
+    if (rendered.length === 0) {
+        if (view.total === 0)
+            return "(no matches)";
+        return `(empty page; ${view.total} total, try offset 0)`;
+    }
+    const body = rendered.join("\n");
+    if (view.remaining === 0)
+        return body;
+    const nextOffset = view.offset + view.rows.length;
+    return `${body}\n\n... and ${view.remaining} more (offset ${nextOffset} to continue)`;
+}
+/**
+ * Defensive shape check for a listing payload. The
+ * `renderResult` callback runs inside pi's render loop,
+ * where a thrown error tanks the frame; trust the cast
+ * only after the shape clears.
+ */
+export function isListingDetails(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return (Array.isArray(v.rows) &&
+        typeof v.total === "number" &&
+        typeof v.offset === "number" &&
+        typeof v.limit === "number" &&
+        typeof v.remaining === "number");
+}
+/**
+ * One-line preview of a listing result for the collapsed
+ * (default) tool widget. Shows the first brief row and a
+ * row-count suffix so the human can tell how much more
+ * is hidden before pressing Ctrl-O. The count combines
+ * the remaining rows on this page with whatever paging
+ * left behind, so a paged result reads honestly. Empty
+ * listings fall back to the rendered content, which
+ * already says `(no matches)` or `(no quests)`.
+ */
+export function collapseListingPreview(listing, content) {
+    if (listing.rows.length === 0)
+        return content.split("\n")[0];
+    const firstRow = content.split("\n")[0];
+    const more = listing.rows.length - 1 + listing.remaining;
+    if (more <= 0)
+        return firstRow;
+    return `${firstRow} (+${more} more)`;
+}
+/**
+ * Collapse a multi-line, non-listing result (show, who, links) for the
+ * human TUI. Expanded or single-line content is returned whole; a
+ * multi-line result collapses to its first line plus a count of the
+ * hidden lines and an expand hint, so the reader knows the rich output
+ * is there and how to see it. This is the counterpart that keeps the
+ * human render and the agent result fed from one text, rather than
+ * silently dropping everything past the first line for the human.
+ */
+export function collapseText(content, expanded, expandHint) {
+    if (expanded)
+        return content;
+    const lines = content.split("\n");
+    if (lines.length <= 1)
+        return content;
+    const hidden = lines.length - 1;
+    return `${lines[0]} (+${count(hidden, "more line")}, ${expandHint})`;
+}

package/dist/quest/state.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Runtime state for the quest workflow. Two layers:
+ *
+ * 1. The loaded quest: which campaign we're currently in.
+ *    There can be at most one at a time.
+ * 2. The focused document: which plan, research, brief or
+ *    report under that quest the agent is currently driving
+ *    through the stage machine. At most one at a time.
+ *
+ * Both layers are caches derived from disk. The quest README
+ * and the focused document are the real sources of truth;
+ * the state holds enough projection to drive the status bar
+ * and the discipline gates without re-reading on every turn.
+ */
+import type { Stage } from "./machine.js";
+import type { DocumentKind, QuestKind, QuestPriority, QuestStatus } from "./types.js";
+/** Runtime state for the loaded quest and focused document. */
+export interface QuestState {
+    /**
+     * Where the quest tree lives on disk. Settled at
+     * extension startup; the user changes it through the
+     * config file.
+     */
+    questsRoot: string;
+    /**
+     * Whether a fresh session may auto-load a quest from its
+     * working directory at session start. When false, a fresh
+     * session stays idle until an explicit `quest load`; the
+     * spawn env-var hint and this session's persisted /reload
+     * history are unaffected. Settled at startup from config;
+     * defaults to true to preserve the cd-and-attach flow.
+     */
+    autoloadFromCwd: boolean;
+    /**
+     * How many days a closed session record is kept before being
+     * forgotten. Settled at startup from config.
+     */
+    sessionRetentionDays: number;
+    /** Absolute path to the loaded quest's directory. */
+    questDir: string | null;
+    /** The loaded quest's id (QEST-...). */
+    questId: string | null;
+    /** The loaded quest's title (H1). */
+    questTitle: string | null;
+    /** The loaded quest's kind. */
+    questKind: QuestKind | null;
+    /** The loaded quest's status. */
+    questStatus: QuestStatus | null;
+    /** The loaded quest's priority bucket. */
+    questPriority: QuestPriority | null;
+    /**
+     * The loaded quest's verification command, or null when it
+     * declares none. Mirrored from the quest frontmatter so the
+     * verification workflow can read it from this session entry
+     * without parsing the quest itself.
+     */
+    questVerify: string | null;
+    /**
+     * The loaded quest's managed scratch directory, or null when it
+     * has none yet. Created on demand under the OS temp dir, recorded
+     * on the quest frontmatter and mirrored here so the gate can
+     * classify scratch writes without a disk read. Reaped on conclude
+     * and retire.
+     */
+    scratchDir: string | null;
+    /** Focused document path under the loaded quest, when one is focused. */
+    documentPath: string | null;
+    /** Focused document id (PLAN-/RSCH-/BRIF-/RPRT-...). */
+    documentId: string | null;
+    /** Focused document kind. */
+    documentKind: DocumentKind | null;
+    /** Focused document title (H1). */
+    documentTitle: string | null;
+    /** Focused document stage. */
+    documentStage: Stage;
+    /**
+     * Progress for the status bar. When a document is
+     * focused, these mirror that document's checkboxes.
+     * Otherwise they mirror the quest README's checkboxes.
+     */
+    done: number;
+    total: number;
+    /**
+     * Verbatim prose of the first unchecked checkbox in the
+     * source the counter walked. Carried so the widget can
+     * paint `→ {item}` without re-parsing the body.
+     */
+    currentItem?: string;
+    /**
+     * Cache of the most recently persisted snapshot's
+     * `${questId ?? ""}|${documentPath ?? ""}` key. The
+     * tool_result hook fires on every tool call; comparing
+     * against this cache is O(1) and avoids reading the
+     * session history from disk to dedup. The cache is
+     * advisory: when it's missing (a fresh session), the
+     * dedup path falls back to `getLastEntry`.
+     */
+    lastPersistedKey?: string;
+}
+/**
+ * Build a fresh, idle state. The caller resolves the
+ * questsRoot from the package config (see
+ * `resolveQuestsRoot` in config.ts) and passes it in, so
+ * this stays a pure constructor with no environment or
+ * filesystem side-effects.
+ */
+export declare function createQuestState(opts: {
+    questsRoot: string;
+    autoloadFromCwd?: boolean;
+    sessionRetentionDays?: number;
+}): QuestState;

package/dist/quest/state.js

@@ -0,0 +1,46 @@
+/**
+ * Runtime state for the quest workflow. Two layers:
+ *
+ * 1. The loaded quest: which campaign we're currently in.
+ *    There can be at most one at a time.
+ * 2. The focused document: which plan, research, brief or
+ *    report under that quest the agent is currently driving
+ *    through the stage machine. At most one at a time.
+ *
+ * Both layers are caches derived from disk. The quest README
+ * and the focused document are the real sources of truth;
+ * the state holds enough projection to drive the status bar
+ * and the discipline gates without re-reading on every turn.
+ */
+import { DEFAULT_SESSION_RETENTION_DAYS } from "./config.js";
+/**
+ * Build a fresh, idle state. The caller resolves the
+ * questsRoot from the package config (see
+ * `resolveQuestsRoot` in config.ts) and passes it in, so
+ * this stays a pure constructor with no environment or
+ * filesystem side-effects.
+ */
+export function createQuestState(opts) {
+    return {
+        questsRoot: opts.questsRoot,
+        autoloadFromCwd: opts.autoloadFromCwd ?? true,
+        sessionRetentionDays: opts.sessionRetentionDays ?? DEFAULT_SESSION_RETENTION_DAYS,
+        questDir: null,
+        questId: null,
+        questTitle: null,
+        questKind: null,
+        questStatus: null,
+        questPriority: null,
+        questVerify: null,
+        scratchDir: null,
+        documentPath: null,
+        documentId: null,
+        documentKind: null,
+        documentTitle: null,
+        documentStage: "idle",
+        done: 0,
+        total: 0,
+        currentItem: undefined,
+        lastPersistedKey: undefined,
+    };
+}