@jitsusama/agentic-harness.core 0.1.0

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

@@ -0,0 +1,125 @@
+/**
+ * Liveness derivation for the pi sessions attached to a quest.
+ *
+ * Liveness is not stored: the persisted {@link QuestSession} shape
+ * is unchanged. This module reads the pi session store to classify
+ * each attached session by how recently its log was written, so
+ * `quest show` and reopening can tell a live session from a dead
+ * one without the agent guessing.
+ */
+import type { QuestSession } from "../../quest/types.js";
+import { type TerminalProbe, type TerminalSessionHandle } from "../../terminal/types.js";
+import type { ProcessIdentity, ProcessProbe } from "./process-liveness.js";
+/**
+ * How a quest's attached session looks right now.
+ *
+ * `live` and `dead` are observed through a probe; `unknown` is the
+ * honest answer when the probe could not observe; `idle` is the
+ * recency fallback for a record that carries no probeable identity;
+ * `conflicted` marks a session claimed by more than one quest with no
+ * resolvable owner; `detached` is authoritative membership.
+ */
+export type SessionLiveness = "live" | "idle" | "detached" | "dead" | "unknown" | "conflicted";
+/**
+ * A session's ephemeral, read-time probe result. Never persisted.
+ * A dimension is present only when the session carries the matching
+ * identity, and each dimension is itself tri-state.
+ */
+export interface SessionObservation {
+    process?: ProcessProbe;
+    pane?: TerminalProbe;
+}
+/**
+ * Everything the derivation needs, computed once per top-level
+ * request: the reference time, each session's last activity, the
+ * probe observations for sessions that carry identity, and the set
+ * of sessions with unresolved multi-quest ownership. Built by
+ * {@link buildLivenessSnapshot} and consumed by {@link deriveLiveness}.
+ */
+export interface LivenessSnapshot {
+    now: Date;
+    activity: ReadonlyMap<string, string>;
+    observations: ReadonlyMap<string, SessionObservation>;
+    conflicted: ReadonlySet<string>;
+}
+/**
+ * Injected dependencies for {@link buildLivenessSnapshot}. Every
+ * side effect (reading a log's activity, probing a process, probing
+ * terminals) is a function so the snapshot builder never shells out
+ * in tests.
+ */
+export interface LivenessSnapshotDeps {
+    now?: Date;
+    activityOf: (sessionId: string) => string | undefined;
+    probeProcess: (id: ProcessIdentity) => ProcessProbe;
+    probeTerminals: (handles: readonly TerminalSessionHandle[]) => Promise<ReadonlyMap<string, TerminalProbe>>;
+    conflicted?: ReadonlySet<string>;
+}
+/**
+ * Render an activity timestamp as a compact relative string
+ * ("just now", "15m ago", "3h ago", "2d ago"). Undefined when there
+ * is no timestamp or it does not parse, so callers drop the clause
+ * rather than print a bare "undefined ago".
+ */
+export declare function formatRelativeAge(iso: string | undefined, now: Date): string | undefined;
+/** A {@link QuestSession} enriched with derived liveness. */
+export interface SessionView extends QuestSession {
+    liveness: SessionLiveness;
+    lastActivity?: string;
+}
+/**
+ * Drop a quest's no-log phantom sessions. A phantom is a detached
+ * session with no log file: a fan-out of ephemeral children leaves
+ * such ids behind, and they can never be resumed. Active sessions
+ * are never removed (the current one may not have flushed a log
+ * yet), and a detached session that still has a log is real history.
+ */
+export declare function prunePhantomSessions(sessions: QuestSession[], hasLog: (id: string) => boolean): {
+    kept: QuestSession[];
+    removed: QuestSession[];
+};
+/**
+ * Index every session log in the store once, mapping session id to
+ * its file path. Callers that need the activity of many sessions
+ * (the activity-window query over the whole backlog) build this
+ * once and reuse it, instead of re-listing the store per session.
+ */
+export declare function indexSessionFiles(sessionDir: string): Map<string, string>;
+/**
+ * The most recent activity timestamp across a quest's sessions,
+ * using a prebuilt {@link indexSessionFiles} map. Undefined when
+ * none of them has a log. This is a quest's effective last-touched
+ * time for activity-window filtering and sorting.
+ */
+export declare function questLastActivity(sessions: QuestSession[], index: Map<string, string>): string | undefined;
+export declare function buildLivenessSnapshot(sessions: readonly QuestSession[], deps: LivenessSnapshotDeps): Promise<LivenessSnapshot>;
+/**
+ * Classify an attached session over a prebuilt {@link
+ * LivenessSnapshot}. Membership wins first: a detached session reads
+ * detached and a conflicted one reads conflicted, whatever a probe
+ * saw. A session that carries identity is judged by observation
+ * alone (a matching process or a present pane is live; a gone
+ * process or an absent pane is dead; anything the probe could not
+ * resolve is unknown). A record with no captured identity falls back
+ * to the recency window, the only place recency drives liveness.
+ */
+export declare function deriveLiveness(session: QuestSession, snapshot: LivenessSnapshot): SessionView;
+/**
+ * Locate a session's log file by id and read its newest activity.
+ *
+ * Pi stores sessions as `<sessionDir>/<cwd-encoded>/<ts>_<id>.jsonl`,
+ * so we scan one level of cwd-encoded subdirectories (and the root,
+ * defensively) for a file whose name ends with `_<id>.jsonl`. The
+ * newest entry's timestamp is normalized to an ISO string; pi has
+ * written both epoch-millisecond numbers and ISO strings over time.
+ */
+export declare function sessionActivity(id: string, sessionDir: string): {
+    path: string;
+    lastActivity: string;
+} | undefined;
+/**
+ * A session's last activity resolved from a prebuilt {@link
+ * indexSessionFiles} map, without re-walking the store. This is the
+ * `activityOf` a real {@link buildLivenessSnapshot} passes in.
+ */
+export declare function activityFromIndex(index: ReadonlyMap<string, string>, id: string): string | undefined;

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

@@ -0,0 +1,386 @@
+/**
+ * Liveness derivation for the pi sessions attached to a quest.
+ *
+ * Liveness is not stored: the persisted {@link QuestSession} shape
+ * is unchanged. This module reads the pi session store to classify
+ * each attached session by how recently its log was written, so
+ * `quest show` and reopening can tell a live session from a dead
+ * one without the agent guessing.
+ */
+import { closeSync, fstatSync, openSync, readdirSync, readSync, } from "node:fs";
+import { join } from "node:path";
+import { terminalHandleKey, } from "../../terminal/types.js";
+/**
+ * Render an activity timestamp as a compact relative string
+ * ("just now", "15m ago", "3h ago", "2d ago"). Undefined when there
+ * is no timestamp or it does not parse, so callers drop the clause
+ * rather than print a bare "undefined ago".
+ */
+export function formatRelativeAge(iso, now) {
+    if (!iso)
+        return undefined;
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return undefined;
+    const seconds = Math.max(0, Math.floor((now.getTime() - then) / 1000));
+    if (seconds < 60)
+        return "just now";
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+/**
+ * A session is live when its log was written within this window;
+ * older activity reads as idle. This is a recency heuristic, not a
+ * process probe (see the plan's open question on liveness depth).
+ */
+const LIVE_WINDOW_MS = 15 * 60 * 1000;
+/**
+ * Drop a quest's no-log phantom sessions. A phantom is a detached
+ * session with no log file: a fan-out of ephemeral children leaves
+ * such ids behind, and they can never be resumed. Active sessions
+ * are never removed (the current one may not have flushed a log
+ * yet), and a detached session that still has a log is real history.
+ */
+export function prunePhantomSessions(sessions, hasLog) {
+    const kept = [];
+    const removed = [];
+    for (const session of sessions) {
+        if (session.status === "detached" && !hasLog(session.id)) {
+            removed.push(session);
+        }
+        else {
+            kept.push(session);
+        }
+    }
+    return { kept, removed };
+}
+/**
+ * Index every session log in the store once, mapping session id to
+ * its file path. Callers that need the activity of many sessions
+ * (the activity-window query over the whole backlog) build this
+ * once and reuse it, instead of re-listing the store per session.
+ */
+export function indexSessionFiles(sessionDir) {
+    const index = new Map();
+    const add = (dir, names) => {
+        for (const name of names) {
+            if (!name.endsWith(".jsonl"))
+                continue;
+            const underscore = name.lastIndexOf("_");
+            if (underscore < 0)
+                continue;
+            const id = name.slice(underscore + 1, name.length - ".jsonl".length);
+            if (!index.has(id))
+                index.set(id, join(dir, name));
+        }
+    };
+    let entries;
+    try {
+        entries = readdirSync(sessionDir, { withFileTypes: true });
+    }
+    catch {
+        // Store does not exist or is unreadable; an empty index reads
+        // the same as "no session has a log".
+        return index;
+    }
+    add(sessionDir, entries.filter((e) => e.isFile()).map((e) => e.name));
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const full = join(sessionDir, entry.name);
+        try {
+            add(full, readdirSync(full));
+        }
+        catch {
+            // Unreadable subdir; skip it and keep indexing siblings.
+        }
+    }
+    return index;
+}
+/**
+ * The most recent activity timestamp across a quest's sessions,
+ * using a prebuilt {@link indexSessionFiles} map. Undefined when
+ * none of them has a log. This is a quest's effective last-touched
+ * time for activity-window filtering and sorting.
+ */
+export function questLastActivity(sessions, index) {
+    let newest;
+    for (const session of sessions) {
+        const path = index.get(session.id);
+        if (!path)
+            continue;
+        const last = newestTimestamp(path);
+        if (!last)
+            continue;
+        if (!newest || Date.parse(last) > Date.parse(newest))
+            newest = last;
+    }
+    return newest;
+}
+/**
+ * Build the read-time snapshot for a set of sessions: record each
+ * session's activity, probe every process identity once, and issue
+ * one batched terminal probe for the handles that carry a terminal
+ * identity. A terminal handle's host is taken from the session's
+ * process identity, since a session's terminal lives on the same
+ * host as its process. Runs once per request; the derivation over
+ * it is synchronous.
+ */
+/**
+ * The host a session's terminal was captured on. Prefer the host
+ * recorded on the terminal itself; fall back to the process host for
+ * a legacy record written before the terminal carried its own host.
+ */
+function terminalHostOf(session) {
+    return session.terminal?.hostId ?? session.process?.hostId ?? "";
+}
+export async function buildLivenessSnapshot(sessions, deps) {
+    const now = deps.now ?? new Date();
+    const activity = new Map();
+    const handles = [];
+    for (const session of sessions) {
+        const last = deps.activityOf(session.id);
+        if (last)
+            activity.set(session.id, last);
+        if (session.terminal) {
+            handles.push({
+                driverId: session.terminal.driverId,
+                kind: `${session.terminal.driverId}-pane`,
+                hostId: terminalHostOf(session),
+                scope: session.terminal.scope,
+                value: session.terminal.value,
+            });
+        }
+    }
+    const paneProbes = handles.length > 0
+        ? await deps.probeTerminals(handles)
+        : new Map();
+    const observations = new Map();
+    for (const session of sessions) {
+        if (!session.process && !session.terminal)
+            continue;
+        const obs = {};
+        if (session.process)
+            obs.process = deps.probeProcess(session.process);
+        if (session.terminal) {
+            const key = terminalHandleKey({
+                driverId: session.terminal.driverId,
+                kind: `${session.terminal.driverId}-pane`,
+                hostId: terminalHostOf(session),
+                scope: session.terminal.scope,
+                value: session.terminal.value,
+            });
+            obs.pane = paneProbes.get(key) ?? "unknown";
+        }
+        observations.set(session.id, obs);
+    }
+    return {
+        now,
+        activity,
+        observations,
+        conflicted: deps.conflicted ?? new Set(),
+    };
+}
+/**
+ * Classify an attached session over a prebuilt {@link
+ * LivenessSnapshot}. Membership wins first: a detached session reads
+ * detached and a conflicted one reads conflicted, whatever a probe
+ * saw. A session that carries identity is judged by observation
+ * alone (a matching process or a present pane is live; a gone
+ * process or an absent pane is dead; anything the probe could not
+ * resolve is unknown). A record with no captured identity falls back
+ * to the recency window, the only place recency drives liveness.
+ */
+export function deriveLiveness(session, snapshot) {
+    const lastActivity = snapshot.activity.get(session.id);
+    if (session.status === "detached") {
+        return { ...session, liveness: "detached", lastActivity };
+    }
+    if (snapshot.conflicted.has(session.id)) {
+        return { ...session, liveness: "conflicted", lastActivity };
+    }
+    const observation = snapshot.observations.get(session.id);
+    if ((session.process || session.terminal) && observation) {
+        return {
+            ...session,
+            liveness: observedLiveness(observation),
+            lastActivity,
+        };
+    }
+    if (!lastActivity)
+        return { ...session, liveness: "dead" };
+    const age = snapshot.now.getTime() - Date.parse(lastActivity);
+    const liveness = age <= LIVE_WINDOW_MS ? "live" : "idle";
+    return { ...session, liveness, lastActivity };
+}
+/**
+ * Reduce a probe observation to a liveness verdict. The process
+ * dimension is authoritative and checked first, so a gone process
+ * reads dead even when a stale pane lingers; a present pane rescues
+ * a session whose process could not be probed; everything else the
+ * probe could not resolve is unknown.
+ */
+function observedLiveness(observation) {
+    if (observation.process === "matching")
+        return "live";
+    if (observation.process === "gone")
+        return "dead";
+    if (observation.pane === "present")
+        return "live";
+    if (observation.pane === "absent")
+        return "dead";
+    return "unknown";
+}
+/**
+ * Locate a session's log file by id and read its newest activity.
+ *
+ * Pi stores sessions as `<sessionDir>/<cwd-encoded>/<ts>_<id>.jsonl`,
+ * so we scan one level of cwd-encoded subdirectories (and the root,
+ * defensively) for a file whose name ends with `_<id>.jsonl`. The
+ * newest entry's timestamp is normalized to an ISO string; pi has
+ * written both epoch-millisecond numbers and ISO strings over time.
+ */
+export function sessionActivity(id, sessionDir) {
+    const suffix = `_${id}.jsonl`;
+    const match = findSessionFile(sessionDir, suffix);
+    return activityFromPath(match);
+}
+/**
+ * A session's last activity resolved from a prebuilt {@link
+ * indexSessionFiles} map, without re-walking the store. This is the
+ * `activityOf` a real {@link buildLivenessSnapshot} passes in.
+ */
+export function activityFromIndex(index, id) {
+    return activityFromPath(index.get(id))?.lastActivity;
+}
+/**
+ * Read a known log path's newest activity. Shared by the
+ * directory-walk and the prebuilt-index resolution paths so both
+ * report activity identically. Undefined when the path is missing
+ * or carries no parseable timestamp.
+ */
+function activityFromPath(path) {
+    if (!path)
+        return undefined;
+    const lastActivity = newestTimestamp(path);
+    if (!lastActivity)
+        return undefined;
+    return { path, lastActivity };
+}
+/** Walk the session dir and its immediate subdirs for the id-matched file. */
+function findSessionFile(sessionDir, suffix) {
+    let entries;
+    try {
+        entries = readdirSync(sessionDir, { withFileTypes: true });
+    }
+    catch {
+        // Session dir does not exist or is unreadable; the caller
+        // treats this the same as "no session file found".
+        return undefined;
+    }
+    for (const entry of entries) {
+        const full = join(sessionDir, entry.name);
+        if (entry.isFile() && entry.name.endsWith(suffix))
+            return full;
+        if (entry.isDirectory()) {
+            let inner;
+            try {
+                inner = readdirSync(full);
+            }
+            catch {
+                // Unreadable subdir; skip it and keep scanning siblings.
+                continue;
+            }
+            const hit = inner.find((name) => name.endsWith(suffix));
+            if (hit)
+                return join(full, hit);
+        }
+    }
+    return undefined;
+}
+/**
+ * How much of a session log's tail to read for its newest
+ * timestamp. Logs are append-only and can grow large, so reading
+ * the whole file just to find the latest entry is wasteful; the
+ * last window holds the recent entries.
+ */
+const TAIL_BYTES = 64 * 1024;
+/**
+ * Read the newest entry's timestamp from a JSONL session file.
+ *
+ * Reads only the tail rather than the whole file, and returns the
+ * maximum timestamp among the lines it reads rather than the last
+ * positional one, so a late-arriving out-of-order entry does not
+ * mis-report activity.
+ */
+function newestTimestamp(path) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        // File vanished between listing and reading; no activity.
+        return undefined;
+    }
+    try {
+        const { size } = fstatSync(fd);
+        const start = Math.max(0, size - TAIL_BYTES);
+        const length = size - start;
+        const buffer = Buffer.alloc(length);
+        if (length > 0)
+            readSync(fd, buffer, 0, length, start);
+        let text = buffer.toString("utf8");
+        // When we started mid-file the first line is likely partial;
+        // drop it so a truncated JSON line is not parsed.
+        if (start > 0) {
+            const newline = text.indexOf("\n");
+            if (newline >= 0)
+                text = text.slice(newline + 1);
+        }
+        let newest;
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed === "")
+                continue;
+            const stamp = parseTimestamp(trimmed);
+            if (stamp && (!newest || Date.parse(stamp) > Date.parse(newest))) {
+                newest = stamp;
+            }
+        }
+        return newest;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Parse one JSONL line's timestamp into an ISO string. */
+function parseTimestamp(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        // A partially written final line; fall back to an earlier one.
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const raw = parsed.timestamp;
+    if (typeof raw === "number")
+        return new Date(raw).toISOString();
+    if (typeof raw === "string") {
+        const ms = Date.parse(raw);
+        if (!Number.isNaN(ms))
+            return new Date(ms).toISOString();
+    }
+    return undefined;
+}

package/dist/internal/quest/session-ownership.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Ownership resolution from a session's own log.
+ *
+ * A quest's `sessions:` frontmatter is a denormalized index; the
+ * authoritative current quest of a session is whatever quest-workflow
+ * entry its pi log recorded last. Reconciliation and repair read this
+ * so they can resolve a session claimed by several quests from the
+ * session's recorded intent rather than from a liveness probe.
+ */
+/**
+ * The quest a session is authoritatively on, from the last
+ * quest-workflow entry in its log. Undefined when the log has no such
+ * entry, the last one cleared the quest, or the log cannot be read.
+ * Reads a bounded tail rather than the whole file. A real session log
+ * reached 1.2 GB, and V8 caps a string near 512 MB, so reading it
+ * whole allocated a gigabyte and then threw, leaving that session
+ * permanently unresolvable. The deciding entry is the last one, so
+ * the end of the log is where the answer lives; a quest named only
+ * further back than the window reads as no answer, which is what an
+ * unreadable log already returned.
+ */
+export declare function authoritativeQuestFromLog(logPath: string): string | undefined;

package/dist/internal/quest/session-ownership.js

@@ -0,0 +1,100 @@
+/**
+ * Ownership resolution from a session's own log.
+ *
+ * A quest's `sessions:` frontmatter is a denormalized index; the
+ * authoritative current quest of a session is whatever quest-workflow
+ * entry its pi log recorded last. Reconciliation and repair read this
+ * so they can resolve a session claimed by several quests from the
+ * session's recorded intent rather than from a liveness probe.
+ */
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+/**
+ * How much of a log's end to read. Comfortably more than the last
+ * entries of any ordinary session, and small enough that reading it
+ * costs nothing next to the gigabyte the whole-file read could.
+ */
+const LOG_TAIL_BYTES = 1024 * 1024;
+/**
+ * The last {@link LOG_TAIL_BYTES} of a file, decoded as text.
+ *
+ * The first line is dropped when the file is longer than the window,
+ * since the window almost certainly lands mid-line and a half-entry
+ * would only fail to parse. Nothing else compensates for the cut: a
+ * caller that needs the whole log should not be using this.
+ */
+function readLogTail(path) {
+    const fd = openSync(path, "r");
+    try {
+        const { size } = fstatSync(fd);
+        const length = Math.min(size, LOG_TAIL_BYTES);
+        const buffer = Buffer.allocUnsafe(length);
+        readSync(fd, buffer, 0, length, size - length);
+        const text = buffer.toString("utf8");
+        if (size <= LOG_TAIL_BYTES)
+            return text;
+        const firstBreak = text.indexOf("\n");
+        return firstBreak === -1 ? "" : text.slice(firstBreak + 1);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * The quest a session is authoritatively on, from the last
+ * quest-workflow entry in its log. Undefined when the log has no such
+ * entry, the last one cleared the quest, or the log cannot be read.
+ * Reads a bounded tail rather than the whole file. A real session log
+ * reached 1.2 GB, and V8 caps a string near 512 MB, so reading it
+ * whole allocated a gigabyte and then threw, leaving that session
+ * permanently unresolvable. The deciding entry is the last one, so
+ * the end of the log is where the answer lives; a quest named only
+ * further back than the window reads as no answer, which is what an
+ * unreadable log already returned.
+ */
+export function authoritativeQuestFromLog(logPath) {
+    let text;
+    try {
+        text = readLogTail(logPath);
+    }
+    catch {
+        // Log missing or unreadable: no authoritative answer.
+        return undefined;
+    }
+    let current;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            // A partially written line; skip it and keep scanning.
+            continue;
+        }
+        const questId = questIdOfEntry(entry);
+        if (questId !== false)
+            current = questId;
+    }
+    return current;
+}
+/**
+ * The questId a quest-workflow log entry records, `undefined` when it
+ * cleared the quest, or `false` when the entry is not a quest-workflow
+ * entry at all (so the scan leaves the running value untouched).
+ */
+function questIdOfEntry(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const e = entry;
+    if (e.type !== "custom" || e.customType !== "quest-workflow")
+        return false;
+    const data = e.data;
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const questId = data.questId;
+    return typeof questId === "string" && questId.length > 0
+        ? questId
+        : undefined;
+}