@jitsusama/agentic-harness.core 0.1.0

package/dist/quest/lookup.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Read-only projections over the quest tree: find, who, links,
+ * tree, expand, ancestors, locate and a lean show. Pure functions
+ * over discoverQuests' index — no I/O beyond the read discovery
+ * already does, no host coupling.
+ *
+ * Deliberately excluded, and left to each adapter: anything keyed
+ * to a host's own session log (workspace/recent/restore, an
+ * activity-sorted find, per-session liveness in show) and cast
+ * identity resolution. Those need a session store or identity
+ * registry that not every host has an equivalent for. pi's own
+ * `lookup.ts` layers that richness on top of these same
+ * projections; a CLI adapter that has no session log just renders
+ * what's here.
+ */
+import { type QuestEntry, type QuestIndex } from "../internal/quest/discovery.js";
+import { type CastEntry, type QuestFrontMatter } from "./index.js";
+import type { QuestState } from "./state.js";
+export interface FindParams {
+    query?: string;
+    since?: string;
+    until?: string;
+    field?: "started" | "updated" | "due" | "eta";
+    priority?: string;
+    kind?: string;
+    status?: string;
+    parent?: string;
+    refType?: string;
+}
+/** Fill in `resolveRefQuery`'s defaults for a raw params bag. */
+export declare function resolveRefQuery(params: FindParams): FindParams;
+export interface FindHit {
+    id: string;
+    title: string | null;
+    kind: string;
+    status: string;
+    priority: string;
+    rank: number;
+    updated: string;
+    dir: string;
+    summary?: string;
+}
+export interface QuestRowExpansion {
+    summary?: string;
+    cast: {
+        role: string;
+        subject: string;
+    }[];
+    documents: {
+        id: string;
+        stage: string;
+    }[];
+    recentJourney: {
+        date: string;
+        prose: string;
+    }[];
+}
+/** Build the expansion block for a single quest entry. */
+export declare function buildRowExpansion(entry: QuestEntry): QuestRowExpansion;
+/**
+ * Match a quest against a free-text query, token by token. The
+ * query is split on whitespace and every token must appear
+ * somewhere across the quest's title, id, body or alias values
+ * (an AND across a combined haystack), so a multi-word query no
+ * longer demands one contiguous substring. An empty query
+ * matches everything.
+ */
+export declare function matchesQuery(entry: QuestEntry, q: string): boolean;
+/**
+ * Search quests by free text, time range and frontmatter
+ * filters. Returns every match ordered by `updated`
+ * descending; pagination is the caller's concern so the
+ * listing renderer can attach an accurate "and N more"
+ * tail.
+ */
+export declare function findQuests(state: QuestState, params: FindParams): FindHit[];
+/**
+ * Same as `findQuests` but also returns the matching
+ * `QuestEntry` so the caller can build the expanded view
+ * without re-walking discovery.
+ */
+export declare function findQuestEntries(state: QuestState, params: FindParams): {
+    hit: FindHit;
+    entry: QuestEntry;
+}[];
+/** Convenience: load a single QuestEntry by id. */
+export declare function getQuestEntry(state: QuestState, id: string): QuestEntry | undefined;
+/** A quest that owns the located needle, and how it matched. */
+export interface LocateHit {
+    questId: string;
+    questTitle: string | null;
+    matchKind: "quest" | "document" | "alias" | "session";
+    /** The concrete thing that matched: a doc path, alias ref or id. */
+    detail?: string;
+}
+/**
+ * Inverse index: resolve a needle to the quest that owns it. The
+ * needle may be a quest id, a document id, an alias ref (either
+ * `type:value` or a bare value) or a session id. Returns one hit
+ * per match, so a needle that resolves to several quests (a session
+ * id left on more than one after divergence, say) surfaces them all
+ * rather than hiding the ambiguity behind a single answer.
+ */
+export declare function locateOwner(state: QuestState, needle: string): LocateHit[];
+/** One quest on the ancestor chain, nearest parent first. */
+export interface AncestorHit {
+    id: string;
+    title: string | null;
+    kind: string;
+    status: string;
+}
+/**
+ * Walk a quest's parent chain from its immediate parent up to the
+ * root, so a caller can ask which epic a quest sits under. Nearest
+ * parent comes first. A cycle (a store that drifted into one) or a
+ * dangling parent stops the walk rather than looping forever. Returns
+ * an empty list for a top-level quest, and undefined when the starting
+ * id is unknown.
+ */
+export declare function ancestorsOf(state: QuestState, id: string): AncestorHit[] | undefined;
+export interface WhoParams {
+    name?: string;
+    role?: string;
+    limit?: number;
+}
+export interface WhoHit {
+    questId: string;
+    questTitle: string | null;
+    role: string;
+    subject: string;
+    prose: string;
+}
+/**
+ * Return Cast bullets across quests matching the filter.
+ * No internal cap: the caller owns pagination so a caller
+ * who walks the whole tree gets the whole tree. Direct
+ * library callers who want a cap pass `limit:`.
+ *
+ * Scaffold placeholder subjects (the `_name or @handle_`
+ * sentinel a fresh quest's template writes) are already
+ * filtered out at the parser level by `extractCast`, so
+ * this function only sees real cast bullets.
+ */
+export declare function findPeople(state: QuestState, params: WhoParams): WhoHit[];
+export interface LinkSnippet {
+    questId: string;
+    questTitle: string | null;
+    context: string;
+    /**
+     * Relation the source document used to mention the
+     * loaded quest's id. `produced` when the mention was
+     * preceded by the → sigil; `reference` otherwise.
+     */
+    relation: "produced" | "reference";
+}
+export interface LinkBundle {
+    quests: {
+        id: string;
+        title: string | null;
+    }[];
+    refs: {
+        type: string;
+        value: string;
+        url?: string;
+        why?: string;
+    }[];
+    urls: string[];
+}
+export interface LinksParams {
+    kind?: string;
+    pattern?: string;
+    priority?: string;
+    status?: string;
+}
+export interface LinksResult {
+    outgoing: LinkBundle;
+    incoming: LinkSnippet[];
+}
+/** Outgoing and incoming reference projection for the loaded quest. */
+export declare function linksForLoaded(state: QuestState, params?: LinksParams): LinksResult | undefined;
+/** Outgoing and incoming reference projection for any quest by id. */
+export declare function linksForQuest(index: QuestIndex, questId: string, params: LinksParams): LinksResult | undefined;
+export interface DocumentSummary {
+    id: string;
+    kind: string;
+    stage: string;
+    title: string | null;
+    path: string;
+    updated: string;
+}
+export interface QuestShowResult {
+    frontMatter: QuestFrontMatter;
+    title: string | null;
+    summary: string | null;
+    purpose: string | null;
+    cast: CastEntry[];
+    journey: {
+        date: string;
+        prose: string;
+    }[];
+    milestones: {
+        total: number;
+        done: number;
+    };
+    documents: DocumentSummary[];
+    links: LinkBundle;
+    echoes: LinkSnippet[];
+}
+/** Build the full `show` projection for the loaded quest. */
+export declare function showLoaded(state: QuestState): QuestShowResult | undefined;
+/**
+ * Build the full `show` projection for any quest by id, without
+ * touching the loaded state. This is what lets `show <id>`
+ * inspect a sibling read-only instead of having to load it.
+ *
+ * Deliberately leaner than pi's own `showQuestById`: no attached-
+ * session liveness (that needs pi's session log) and cast subjects
+ * are not resolved to identities (that needs `lib/people`, not yet
+ * ported). Both are adapter-side enrichments a host with a session
+ * log or an identity registry can layer on top of this projection.
+ */
+export declare function showQuestById(state: QuestState, questId: string): QuestShowResult | undefined;
+export interface TreeNode {
+    id: string;
+    title: string | null;
+    kind: string;
+    status: string;
+    priority: string;
+    rank: number;
+    children: TreeNode[];
+}
+/** Tree projection across the whole quest tree.
+ *
+ * Any quest whose `parent` points at an id not in the
+ * index is collected under a synthetic root with a
+ * `parent` of `null` (a deleted or missing parent
+ * shouldn't make the children disappear from the tree
+ * view). The orphans group sits after the legitimate
+ * top-level quests so the user notices it.
+ */
+export declare function treeAll(index: QuestIndex): TreeNode[];
+/** Subtree rooted at a single quest id. */
+export declare function expandQuest(index: QuestIndex, id: string): TreeNode | undefined;