@jitsusama/agentic-harness.core 0.1.0

package/dist/quest/types.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Public types for the quest library.
+ *
+ * A `Quest` is one node in the hierarchy: a top-level
+ * quest, a subquest under another quest, or a free-standing
+ * sidequest. A `QuestDocument` is one of the four kinds of
+ * focused-work artifact (plan, research, brief, report) that
+ * lives under a quest's directory.
+ */
+export type QuestKind = "quest" | "subquest" | "sidequest";
+export type QuestStatus = "active" | "paused" | "blocked" | "concluded" | "retired";
+export type QuestPriority = "driving" | "active" | "queued" | "bench" | "someday";
+export type DocumentKind = "plan" | "research" | "brief" | "report";
+export type DocumentStage = "think" | "draft" | "build" | "concluded" | "retired";
+/** Alias to an external system entity. */
+export interface QuestAlias {
+    type: string;
+    value: string;
+}
+/** Lifecycle status of a pi session attached to a quest. */
+export type SessionStatus = "active" | "detached";
+/**
+ * A working tree the quest owns. The tree's path is the
+ * canonical identifier; the other fields let `quest show`
+ * render useful state without crawling git.
+ */
+export interface QuestTree {
+    /** Absolute path to the tree's working directory. */
+    path: string;
+    /** Branch checked out in the tree, when applicable. */
+    branch?: string;
+    /** Origin repo's root, when the provider knows it. */
+    repoRoot?: string;
+    /**
+     * Id of the tree provider that created this tree. The
+     * prune side uses this to look up the same provider
+     * later, even when registry order has changed.
+     */
+    providerId: string;
+    /**
+     * Zones loaded into the tree's sparse checkout, when
+     * the provider supports it. The built-in git-worktree
+     * provider leaves this empty; the world dev-tree
+     * provider tracks `tec checkout add` results here.
+     */
+    zones?: string[];
+    /**
+     * How this tree came to be on the quest. `scaffolded`
+     * means the tool created it (via `tree-add`) and may
+     * auto-prune it on conclude or retire. `adopted` means a
+     * pre-existing tree the quest only references; it is
+     * never auto-pruned. An absent marker (legacy or
+     * hand-registered) is treated as keep, never auto-pruned.
+     *
+     * This is advisory ownership state, not a trust boundary: it
+     * lives in the quest README, which the agent may write, so an
+     * already-compromised agent could restamp it. The destructive
+     * prune still refuses a dirty or unmerged tree unless forced, so
+     * the marker is one layer of a defence in depth, not the only
+     * guard on deletion.
+     */
+    origin?: "scaffolded" | "adopted";
+}
+/**
+ * A prune attempt blocked on safety: dirty state, unmerged
+ * branch, attached session. Persisted on the quest so the
+ * workflow can resume the conversation after a restart.
+ *
+ * Stored as an array on `QuestFrontMatter.pendingPrune` so
+ * a quest can carry several blocked trees at once (a
+ * `retire` may surface more than one).
+ */
+export interface PendingPrune {
+    /** Path of the tree the user is trying to prune. */
+    path: string;
+    /** Human-readable reason: "dirty", "unmerged", etc. */
+    reason: string;
+    /** When the prune was attempted. ISO 8601. */
+    detectedAt: string;
+}
+/**
+ * A pi session that has driven a quest. The session id is the
+ * canonical identifier; the other fields are convenience
+ * metadata so a `quest show` can render a useful list without
+ * having to cross-reference pi's session log.
+ */
+export interface QuestSession {
+    id: string;
+    name?: string;
+    cwd?: string;
+    started?: string;
+    status?: SessionStatus;
+    /**
+     * Id minted once per pi process start, identifying which process
+     * holds this session so the lease can be released only by its owner.
+     */
+    instanceId?: string;
+    /**
+     * The OS process identity captured at attach, so liveness can be
+     * probed later. A bare pid is not enough; the host and start token
+     * guard against pid reuse and remote processes.
+     */
+    process?: {
+        hostId: string;
+        pid: number;
+        startToken: string;
+        /**
+         * The boot the process was observed under. A reboot invalidates
+         * every pid at once, so a session recorded under an earlier boot
+         * is dead whatever now holds its pid. Absent on records written
+         * before this was captured, and on hosts that publish no token.
+         */
+        bootToken?: string;
+    };
+    /**
+     * The terminal surface the session ran in, as a probeable handle.
+     * `scope` is the mux socket that makes `value` (a pane id)
+     * meaningful across terminal instances and hosts.
+     */
+    terminal?: {
+        driverId: string;
+        value: string;
+        scope?: string;
+        /**
+         * Host the terminal was captured on. Carried on the terminal
+         * itself so a pane stays probeable even when no process
+         * identity was captured (a host where the start token could not
+         * be read).
+         */
+        hostId?: string;
+    };
+}
+/** Frontmatter for a quest README. */
+export interface QuestFrontMatter {
+    id: string;
+    kind: QuestKind;
+    parent: string | null;
+    status: QuestStatus;
+    priority: QuestPriority;
+    rank: number;
+    started: string;
+    updated: string;
+    due?: string;
+    eta?: string;
+    aliases: QuestAlias[];
+    sessions: QuestSession[];
+    trees?: QuestTree[];
+    pendingPrune?: PendingPrune[];
+    /**
+     * Absolute path to the quest's managed scratch directory, created
+     * on demand under the OS temp dir. Persisted so it survives across
+     * sessions and can be reaped on conclude or retire.
+     */
+    scratchDir?: string;
+    /**
+     * Bag of unrecognised top-level frontmatter keys we read
+     * back from disk so we can write them out unchanged. The
+     * README is human-editable; user-added fields survive
+     * round-trip.
+     */
+    _extra?: Record<string, unknown>;
+    /**
+     * Document id of the plan the agent first drafts on this
+     * quest. The build-stage tree gate consults this so the
+     * "primary plan" definition is deterministic across
+     * file-system orderings.
+     */
+    primaryPlanId?: string;
+    /**
+     * Verification command for work on this quest, run by the
+     * verification workflow's medium layer in preference to a
+     * project script. Lets a quest that spans a subdirectory or
+     * a single zone name the exact check that proves its work,
+     * rather than the whole repo's.
+     */
+    verify?: string;
+}
+/** Frontmatter for a quest document (plan, research, etc.). */
+export interface DocumentFrontMatter {
+    id: string;
+    kind: DocumentKind;
+    quest: string;
+    stage: DocumentStage;
+    updated: string;
+    /**
+     * Round counter for a research doc that records repeated
+     * passes against the same subject (e.g. council reviews).
+     * Persisted in frontmatter so consumers don't have to
+     * count headings in the body to know which round they are
+     * appending.
+     */
+    rounds?: number;
+    /** Subject tag, e.g. "pr-review". Used for round-trip matching. */
+    subject?: string;
+    /** Bag of unrecognised top-level keys, mirrored from QuestFrontMatter. */
+    _extra?: Record<string, unknown>;
+}
+/** A parsed quest README. */
+export interface QuestDoc {
+    frontMatter: QuestFrontMatter;
+    body: string;
+    /** Title from the body's H1, or undefined when absent. */
+    title?: string;
+}
+/** A parsed quest document (plan/research/brief/report). */
+export interface QuestDocumentDoc {
+    frontMatter: DocumentFrontMatter;
+    body: string;
+    title?: string;
+}
+/** A cast bullet parsed out of a quest README's Cast section. */
+export interface CastEntry {
+    /** Role keyword (e.g. "owner", "reviewer"). Lowercase. */
+    role: string;
+    /** The person's name or handle as it appears in the bullet. */
+    subject: string;
+    /** Prose after the subject, including any inline links. */
+    prose: string;
+}
+/** A journey entry parsed out of the Journey section. */
+export interface JourneyEntry {
+    date: string;
+    prose: string;
+}

package/dist/quest/types.js

@@ -0,0 +1,10 @@
+/**
+ * Public types for the quest library.
+ *
+ * A `Quest` is one node in the hierarchy: a top-level
+ * quest, a subquest under another quest, or a free-standing
+ * sidequest. A `QuestDocument` is one of the four kinds of
+ * focused-work artifact (plan, research, brief, report) that
+ * lives under a quest's directory.
+ */
+export {};

package/dist/quest/verbs/alias.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Alias verbs: alias-add and alias-remove. Parses both the
+ * `type:value` literal form and recognised URL shapes
+ * through the refs registry.
+ */
+import type { QuestState } from "../state.js";
+import { type QuestResult, type QuestToolParams } from "./shared.js";
+export declare function aliasAdd(state: QuestState, params: QuestToolParams): QuestResult;
+export declare function aliasRemove(state: QuestState, params: QuestToolParams): QuestResult;

package/dist/quest/verbs/alias.js

@@ -0,0 +1,129 @@
+/**
+ * Alias verbs: alias-add and alias-remove. Parses both the
+ * `type:value` literal form and recognised URL shapes
+ * through the refs registry.
+ */
+import { buildAliasIndex, lookupAliasDetail, } from "../../internal/quest/alias-index.js";
+import { discoverQuests } from "../../internal/quest/discovery.js";
+import { parseRef } from "../../refs/index.js";
+import { addAliasesToLoaded, appendJourneyEntry, removeAliasesFromLoaded, } from "../lifecycle.js";
+import { ok, refuse, } from "./shared.js";
+/**
+ * Parse the user's alias input. Prefers the literal
+ * `type:value` form when the prefix looks like a registered
+ * ref type. Falls back to URL detection via the refs
+ * registry.
+ */
+function parseAliasInput(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    const literal = /^([a-z][a-z0-9-]*):(.+)$/i.exec(trimmed);
+    if (literal) {
+        const type = literal[1].trim();
+        const value = literal[2].trim();
+        if (type && value && !/^https?$/i.test(type)) {
+            return { type, value };
+        }
+    }
+    const ref = parseRef(trimmed);
+    if (ref)
+        return { type: ref.type, value: ref.value };
+    return undefined;
+}
+export function aliasAdd(state, params) {
+    if (!state.questId)
+        return refuse("Load a quest first.");
+    const input = params.ref ?? params.url ?? "";
+    // A comma separates entries: a type:value literal and a URL both
+    // have no bare comma, so splitting first lets one call add several.
+    const tokens = input
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    const aliases = [];
+    for (const token of tokens) {
+        const alias = parseAliasInput(token);
+        if (!alias) {
+            return refuse(`Could not parse "${token}" as an alias. Use the \`type:value\` form (e.g. \`github-pr:shop/world#47281\`) or a recognised URL; separate several with commas.`);
+        }
+        aliases.push(alias);
+    }
+    if (aliases.length === 0) {
+        return refuse("Pass the alias in `ref` (e.g. `github-pr:shop/world#47281`) or in `url` (a recognised URL). Separate several with commas.");
+    }
+    // Refuse a ref that already lives on another quest: routing the
+    // same alias to two quests would mis-attribute the linked work.
+    const { index } = discoverQuests(state.questsRoot);
+    const aliasIdx = buildAliasIndex(index);
+    for (const alias of aliases) {
+        const lookup = lookupAliasDetail(aliasIdx, alias);
+        if (lookup.kind === "collision") {
+            return refuse(`Alias ${alias.type}:${alias.value} is already on multiple quests (${lookup.questIds.join(", ")}). Resolve the duplicate before adding it again.`);
+        }
+        if (lookup.kind === "hit" && lookup.questId !== state.questId) {
+            return refuse(`Alias ${alias.type}:${alias.value} is already on quest ${lookup.questId}. Load that quest, or remove it there first.`);
+        }
+    }
+    // One write lands the whole list, so a mid-list failure cannot
+    // leave a partial set behind.
+    const result = addAliasesToLoaded(state, aliases);
+    if (!result.ok)
+        return refuse(result.guidance);
+    const { added, already } = result;
+    for (const alias of added) {
+        appendJourneyEntry(state, `Linked ${alias.type}:${alias.value}.`);
+    }
+    const label = (a) => `${a.type}:${a.value}`;
+    if (added.length === 0) {
+        return ok(`Alias ${already.map(label).join(", ")} was already present.`, {
+            aliases: already,
+            added: false,
+        });
+    }
+    let message = `Added alias ${added.map(label).join(", ")}.`;
+    if (already.length > 0) {
+        message += ` ${already.map(label).join(", ")} already present.`;
+    }
+    return ok(message, { aliases: added, added: true });
+}
+export function aliasRemove(state, params) {
+    if (!state.questId)
+        return refuse("Load a quest first.");
+    const input = params.ref ?? params.url ?? "";
+    // Accept a comma batch, matching alias-add, so several aliases can be
+    // scrubbed in one call rather than one at a time.
+    const tokens = input
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    const aliases = [];
+    for (const token of tokens) {
+        const alias = parseAliasInput(token);
+        if (!alias) {
+            return refuse(`Could not parse "${token}" as an alias. Use the \`type:value\` form (e.g. \`github-pr:shop/world#47281\`) or a recognised URL; separate several with commas.`);
+        }
+        aliases.push(alias);
+    }
+    if (aliases.length === 0) {
+        return refuse("Pass the alias in `ref` (e.g. `github-pr:shop/world#47281`) or in `url`. Separate several with commas.");
+    }
+    const result = removeAliasesFromLoaded(state, aliases);
+    if (!result.ok)
+        return refuse(result.guidance);
+    const { removed, absent } = result;
+    const label = (a) => `${a.type}:${a.value}`;
+    // A no-op is reported as success, matching alias-add: "nothing to
+    // remove" is the same outcome as "already present", not a refusal.
+    if (removed.length === 0) {
+        return ok(`Alias ${absent.map(label).join(", ")} was not on this quest.`, {
+            aliases: absent,
+            removed: false,
+        });
+    }
+    let message = `Removed alias ${removed.map(label).join(", ")}.`;
+    if (absent.length > 0) {
+        message += ` ${absent.map(label).join(", ")} was not on this quest.`;
+    }
+    return ok(message, { aliases: removed, removed: true });
+}

package/dist/quest/verbs/lifecycle.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Quest-lifecycle verbs: create, load, unload, show, list,
+ * focus, unfocus, reclassify.
+ *
+ * pi's own `verbs/lifecycle.ts` additionally enriches `load` with
+ * automatic session-attach bookkeeping (`ctx.sessionManager`,
+ * `pi.setSessionName`, `recordSessionOnQuest`) and `show`/`list`
+ * with per-session liveness -- all keyed to pi's own session
+ * concept, which no other host has an equivalent for. This version
+ * loads and shows a quest without any of that; an adapter with its
+ * own session story (pi's `verbs/lifecycle.ts` is the example)
+ * layers it on by calling `load`/`show` here and then doing its
+ * own session bookkeeping around the result.
+ */
+import type { QuestState } from "../state.js";
+import { type QuestResult, type QuestToolParams } from "./shared.js";
+/**
+ * Change the loaded quest's kind (quest, subquest or sidequest), so a
+ * misclassification made at create time is fixable in place instead
+ * of forcing a delete-and-recreate.
+ */
+export declare function reclassify(state: QuestState, params: QuestToolParams): QuestResult;
+/** Mint a new quest, optionally seeded from a URL, and load it. */
+export declare function create(state: QuestState, params: QuestToolParams): Promise<QuestResult>;
+/** Load a quest by id. */
+export declare function load(state: QuestState, params: QuestToolParams): QuestResult;
+export declare function unload(state: QuestState): QuestResult;
+/**
+ * Project a quest for `show`, read-only: an explicit id projects
+ * any quest without changing what is loaded; otherwise show the
+ * loaded quest.
+ */
+export declare function show(state: QuestState, params?: QuestToolParams): QuestResult;
+export declare function list(state: QuestState, params: QuestToolParams): QuestResult;
+export declare function focus(state: QuestState, params: QuestToolParams): QuestResult;
+export declare function unfocus(state: QuestState): QuestResult;