@jitsusama/agentic-harness.core 0.1.0

package/dist/quest/lifecycle.d.ts

@@ -0,0 +1,365 @@
+/**
+ * Lifecycle mutations for the quest workflow: focus, unfocus,
+ * document stage, journey entries, aliasing, reordering,
+ * priority/status/parent changes, session attach/detach.
+ *
+ * Everything here operates on a `QuestState` value and plain
+ * arguments, with no dependency on an adapter's own extension API
+ * or session log. The pi-only counterparts -- loading a quest
+ * (which sets pi's session name), persisting/restoring the loaded
+ * quest across a pi session (which reads/writes pi's own session
+ * log), and pruning phantom sessions against pi's session-log
+ * directory -- stay in agentic-harness.pi's own lifecycle.ts,
+ * which imports the mutations here for everything else.
+ */
+import { type AliasIndex } from "../internal/quest/alias-index.js";
+import { type QuestEntry } from "../internal/quest/discovery.js";
+import type { QuestFieldLens } from "../internal/quest/fields.js";
+import { type DocumentKind, type QuestAlias, type QuestFrontMatter, type QuestPriority, type QuestSession, type QuestStatus } from "./index.js";
+import type { Stage } from "./machine.js";
+import type { QuestState } from "./state.js";
+/**
+ * Persist the focused document's progress (or, when no
+ * document is focused, the loaded quest's) into the
+ * QuestState struct so the widget can paint without
+ * re-parsing the body on every keystroke.
+ *
+ * Uses the broad `checkboxProgress` walk so every `- [ ]`
+ * / `- [x]` in the body contributes regardless of which
+ * section holds it. The plan, research, brief and report
+ * templates each use a different section name for their
+ * work list; one counter serves them all.
+ */
+export declare function refreshProgress(state: QuestState): void;
+/** Find a quest entry by id across the quests root. */
+export declare function findQuestEntry(state: QuestState, id: string): QuestEntry | undefined;
+/**
+ * Load a quest by id into `state`: the state-mutation half of pi's
+ * own `loadQuest`. pi's version additionally calls
+ * `pi.setSessionName?.()` once this succeeds -- a pi-only
+ * enrichment with no equivalent host concept, so it stays out of
+ * this pure version; an adapter that wants it layers it on after
+ * calling this.
+ */
+export declare function loadQuestById(state: QuestState, id: string): {
+    ok: true;
+} | {
+    ok: false;
+    guidance: string;
+};
+/**
+ * Re-read the loaded quest's README and refresh the in-memory
+ * slice (title, kind, status, priority) so an edit to the quest's
+ * own README shows up in the status line without a manual reload.
+ * No-op when no quest is loaded or the README cannot be read.
+ */
+export declare function refreshLoadedSlice(state: QuestState): void;
+/** Unload the currently loaded quest. */
+export declare function unloadQuest(state: QuestState): void;
+/** Focus a document under the loaded quest. */
+export declare function focusDocument(state: QuestState, docPath: string): {
+    ok: true;
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Unfocus the active document. */
+export declare function unfocusDocument(state: QuestState): void;
+/**
+ * Persist the focused document's stage to its file and mirror it in
+ * state. Returns true when the stage reached disk, false when there
+ * is nothing to write to or the file is unreadable or unparseable,
+ * so the caller can refuse rather than let memory run ahead of disk.
+ */
+export declare function writeDocumentStage(state: QuestState, stage: Stage): boolean;
+/**
+ * Seal every still-active document under a quest to the quest's
+ * terminal stage, so concluding or retiring a quest does not leave
+ * documents stranded mid-stage. Returns how many were sealed.
+ * Best-effort per file: an unreadable document is skipped, not fatal.
+ */
+export declare function sealQuestDocuments(questDir: string, target: "concluded" | "retired"): number;
+/** Append a Journey entry to the loaded quest's README. */
+export declare function appendJourneyEntry(state: QuestState, prose: string): void;
+/** Update the loaded quest's `updated` frontmatter to today. */
+export declare function stampQuestUpdated(state: QuestState): void;
+/** Create a new document under the loaded quest. */
+export declare function createDocument(state: QuestState, opts: {
+    id: string;
+    kind: DocumentKind;
+    title: string;
+    stage: Stage;
+    scaffoldBody: string;
+}): string | undefined;
+/** One working tree in the cross-quest inventory. */
+export interface WorktreeInventoryEntry {
+    path: string;
+    branch?: string;
+    questId: string;
+    questTitle: string | null;
+    /** Whether the tree's directory still exists on disk. */
+    exists: boolean;
+}
+/**
+ * Inventory every working tree recorded across all quests,
+ * attributing each to its owning quest. This is what lets the
+ * harness-created trees be seen and reaped in one place instead
+ * of being a mystery pile of directories.
+ */
+export declare function inventoryWorktrees(state: QuestState): WorktreeInventoryEntry[];
+/** Discover quests for /quest-list etc. */
+export declare function listAllQuests(state: QuestState): QuestEntry[];
+/** Ensure the quests root exists on disk. */
+export declare function ensureQuestsRoot(state: QuestState): void;
+export type RankAction = {
+    kind: "top";
+} | {
+    kind: "bottom";
+} | {
+    kind: "bump";
+} | {
+    kind: "sink";
+} | {
+    kind: "before";
+    target: string;
+} | {
+    kind: "after";
+    target: string;
+} | {
+    kind: "renumber";
+};
+export interface ReorderResult {
+    siblings: QuestEntry[];
+    changes: {
+        id: string;
+        from: number;
+        to: number;
+    }[];
+}
+/**
+ * Reorder the sibling set the given quest belongs to.
+ * Siblings share both `parent` and `priority`. Writes the
+ * updated rank back to every quest whose rank changed.
+ */
+export declare function reorderSiblings(state: QuestState, questId: string, action: RankAction): {
+    ok: true;
+    result: ReorderResult;
+} | {
+    ok: false;
+    guidance: string;
+};
+/**
+ * Set a quest's rank by directory. The by-dir counterpart to the
+ * internal `writeQuestRank`, exported so undo can reverse a journalled
+ * rank change (a reparent re-ranks into its new sibling set).
+ */
+export declare function setQuestRankByDir(questDir: string, rank: number): {
+    ok: true;
+} | {
+    ok: false;
+    guidance: string;
+};
+/**
+ * Set any journalled field by directory, through the lens that knows
+ * how to write it.
+ *
+ * Undo used to reach for one exported setter per field and cast the
+ * journalled string to that field's type on the way in. The lens
+ * checks the value against the field's vocabulary instead, so a
+ * journal entry carrying a word the vocabulary has since lost is
+ * refused with a reason rather than written back unexamined.
+ */
+export declare function setQuestFieldByDir(questDir: string, lens: QuestFieldLens, value: string | null): {
+    ok: true;
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Build a reverse alias index across every discovered quest. */
+export declare function buildQuestsAliasIndex(state: QuestState): AliasIndex;
+/**
+ * Set a quest's parent by directory, stamping `updated` and
+ * appending a Journey entry. Used by the reparent verb, which
+ * may move quests other than the loaded one.
+ */
+export declare function setQuestParent(questDir: string, newParent: string | null): {
+    ok: true;
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Set a quest's status by directory, stamping `updated`. */
+export declare function setQuestStatusByDir(questDir: string, status: QuestFrontMatter["status"]): {
+    ok: true;
+} | {
+    ok: false;
+    guidance: string;
+};
+/**
+ * Set a quest's priority by directory (the by-id counterpart to
+ * `setLoadedPriority`). Used by the bulk seal cascade and by undo
+ * when it reverses a journalled priority change.
+ */
+export declare function setQuestPriorityByDir(questDir: string, priority: QuestFrontMatter["priority"]): {
+    ok: true;
+} | {
+    ok: false;
+    guidance: string;
+};
+/**
+ * Add one or more aliases to the loaded quest in a single front-matter
+ * write, so a list either lands whole or not at all and no partial
+ * state survives a failure. Aliases already present, and duplicates
+ * within the batch, are reported as already and added only once.
+ */
+export declare function addAliasesToLoaded(state: QuestState, aliases: QuestAlias[]): {
+    ok: true;
+    added: QuestAlias[];
+    already: QuestAlias[];
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Remove an alias from the loaded quest. */
+export declare function removeAliasFromLoaded(state: QuestState, alias: QuestAlias): {
+    ok: true;
+    removed: boolean;
+} | {
+    ok: false;
+    guidance: string;
+};
+/**
+ * Remove one or more aliases from the loaded quest in a single write,
+ * the batch counterpart to addAliasesToLoaded. Reports which were
+ * removed and which were absent, so the verb can signal a partial or
+ * whole no-op the same way the add path does.
+ */
+export declare function removeAliasesFromLoaded(state: QuestState, aliases: QuestAlias[]): {
+    ok: true;
+    removed: QuestAlias[];
+    absent: QuestAlias[];
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Attach a session id to the loaded quest. */
+export declare function attachSessionToLoaded(state: QuestState, session: QuestSession): {
+    ok: true;
+    added: boolean;
+} | {
+    ok: false;
+    guidance: string;
+};
+/**
+ * Capture the current process's liveness identity for a session
+ * attach: its instance id, OS process identity and the terminal
+ * surface it runs in (when a driver recognises one). Read once at
+ * attach time; the stored handle is what a later reader probes.
+ */
+export declare function captureSessionIdentity(): {
+    instanceId: string;
+    process: QuestSession["process"];
+    terminal: QuestSession["terminal"];
+};
+/**
+ * Attach the current session to the loaded quest.
+ *
+ * This is the automatic-capture path: a session-start or load flow
+ * calls it so a quest's sessions frontmatter records where work
+ * happened without the user attaching by hand. It refreshes an
+ * existing record rather than duplicating, and no-ops cleanly when
+ * no quest is loaded or the session id is unknown.
+ */
+export declare function attachCurrentSession(state: QuestState, opts: {
+    id: string | undefined;
+    cwd?: string;
+    persisted?: boolean;
+    instanceId?: string;
+    process?: QuestSession["process"];
+    terminal?: QuestSession["terminal"];
+}): {
+    attached: boolean;
+};
+/**
+ * Detach a session only when the caller's process instance owns the
+ * record, so a process that resumed a session is not detached by the
+ * delayed shutdown of the process that used to hold it. A record with
+ * no recorded instance id is legacy and detaches unconditionally,
+ * preserving the pre-lease behaviour.
+ */
+export declare function detachSessionIfOwner(questDir: string, sessionId: string, instanceId: string): {
+    ok: true;
+    detached: boolean;
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Mark a session as detached on the loaded quest. */
+export declare function detachSessionFromLoaded(state: QuestState, sessionId: string): {
+    ok: true;
+    detached: boolean;
+} | {
+    ok: false;
+    guidance: string;
+};
+/**
+ * Reconcile a session's membership so it reads active on exactly one
+ * quest: detach the session from every quest other than the one being
+ * kept. The switch path already releases the immediate prior quest;
+ * this catches stragglers left by earlier runs or a lost state, so a
+ * session never lingers active on several quests at once. Returns the
+ * ids it detached the session from.
+ */
+export declare function reconcileSessionMembership(state: QuestState, sessionId: string, keepQuestId: string): string[];
+export declare function detachSessionInQuestDir(questDir: string, sessionId: string): {
+    ok: true;
+    detached: boolean;
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Set the loaded quest's priority bucket. */
+export declare function setLoadedPriority(state: QuestState, priority: QuestPriority): {
+    ok: true;
+    changed: boolean;
+} | {
+    ok: false;
+    guidance: string;
+};
+/**
+ * Change the loaded quest's kind. A subquest needs a parent to rank
+ * within, so refuse the move to subquest when the quest has none.
+ * Returns whether the kind actually changed.
+ */
+export declare function setLoadedKind(state: QuestState, kind: QuestFrontMatter["kind"]): {
+    ok: true;
+    changed: boolean;
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Shift the loaded quest one bucket up or down the priority ladder. */
+export declare function bumpLoadedPriority(state: QuestState, direction: "up" | "down"): {
+    ok: true;
+    from: QuestPriority;
+    to: QuestPriority;
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Set the loaded quest's coarse status enum. */
+export declare function setLoadedStatus(state: QuestState, status: QuestStatus): {
+    ok: true;
+    changed: boolean;
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Rename a session on the loaded quest. */
+export declare function renameSessionOnLoaded(state: QuestState, sessionId: string, name: string): {
+    ok: true;
+    renamed: boolean;
+} | {
+    ok: false;
+    guidance: string;
+};