@kynetic-ai/spec 0.9.1 → 0.10.0

package/dist/sessions/store.js

@@ -17,6 +17,7 @@ import * as path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { parse as parseTOML, stringify as stringifyTOML } from "smol-toml";
 import * as YAML from "yaml";
+import { shadowAutoCommit } from "../parser/shadow.js";
 import { SessionEventSchema, SessionMetadataSchema, TaskBudgetSchema, } from "./types.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 const SESSIONS_DIR = "sessions";
@@ -29,6 +30,7 @@ const BLOBS_DIR = "blobs";
 const EVENT_LINE_MAX_BYTES = 256 * 1024;
 const EVENT_FIELD_EXTERNALIZE_BYTES = 16 * 1024;
 const EVENT_PREVIEW_MAX_BYTES = 512;
+const EVENT_SEQ_TAIL_READ_BYTES = EVENT_LINE_MAX_BYTES + 1024;
 // ─── Path Helpers ────────────────────────────────────────────────────────────
 /**
  * Get the sessions directory path within a spec directory.
@@ -90,10 +92,13 @@ export async function createSession(specDir, input) {
     // Create session directory
     await fsPromises.mkdir(sessionDir, { recursive: true });
     // Build full metadata
+    // AC: @session-model-evolution ac-1 — include trigger and agent_id when provided
     const metadata = {
         id: input.id,
         task_id: input.task_id,
         agent_type: input.agent_type,
+        agent_id: input.agent_id,
+        trigger: input.trigger,
         status: input.status ?? "active",
         started_at: input.started_at ?? new Date().toISOString(),
         ended_at: undefined,
@@ -120,7 +125,13 @@ export async function getSession(specDir, sessionId) {
     try {
         const content = await fsPromises.readFile(metadataPath, "utf-8");
         const raw = YAML.parse(content);
-        return SessionMetadataSchema.parse(raw);
+        const parsed = SessionMetadataSchema.parse(raw);
+        // AC: @session-model-evolution ac-2 — materialize defaults for legacy sessions
+        return {
+            ...parsed,
+            trigger: parsed.trigger ?? "legacy",
+            agent_id: parsed.agent_id ?? parsed.agent_type,
+        };
     }
     catch {
         return null;
@@ -443,22 +454,70 @@ export async function resolveSessionBlobPointers(specDir, sessionId, value) {
     }
     return value;
 }
+function extractLastEventSeq(content) {
+    const lines = content.split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = lines[i].trim();
+        if (line.length === 0) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(line);
+            if (isRecord(parsed) &&
+                typeof parsed.seq === "number" &&
+                Number.isInteger(parsed.seq) &&
+                parsed.seq >= 0) {
+                return parsed.seq;
+            }
+        }
+        catch {
+            // Ignore malformed lines and continue scanning backward.
+        }
+    }
+    return null;
+}
 /**
- * Get the current event count for a session (for seq assignment).
+ * Get next sequence number from the last stored event.
  *
- * @param specDir - The .kspec directory path
- * @param sessionId - Session ID
- * @returns Number of events in the session
+ * Reads a bounded tail slice for O(1) seq lookup; falls back to full scan only
+ * if the tail slice cannot be parsed (for example, partial line boundary).
  */
-async function getEventCount(specDir, sessionId) {
+async function getNextEventSeq(specDir, sessionId) {
     const eventsPath = getSessionEventsPath(specDir, sessionId);
+    let fileHandle = null;
     try {
-        const content = await fsPromises.readFile(eventsPath, "utf-8");
-        const lines = content
-            .trim()
-            .split("\n")
-            .filter((line) => line.length > 0);
-        return lines.length;
+        fileHandle = await fsPromises.open(eventsPath, "r");
+        const stats = await fileHandle.stat();
+        if (stats.size === 0) {
+            return 0;
+        }
+        const readBytes = Math.min(stats.size, EVENT_SEQ_TAIL_READ_BYTES);
+        const startOffset = stats.size - readBytes;
+        const buffer = Buffer.alloc(readBytes);
+        await fileHandle.read(buffer, 0, readBytes, startOffset);
+        let tailContent = buffer.toString("utf-8");
+        if (startOffset > 0) {
+            // Drop potential partial first line from tail slice.
+            const firstNewline = tailContent.indexOf("\n");
+            tailContent = firstNewline === -1 ? "" : tailContent.slice(firstNewline + 1);
+        }
+        const tailSeq = extractLastEventSeq(tailContent);
+        if (tailSeq !== null) {
+            return tailSeq + 1;
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return 0;
+        }
+    }
+    finally {
+        await fileHandle?.close().catch(() => undefined);
+    }
+    try {
+        const fullContent = await fsPromises.readFile(eventsPath, "utf-8");
+        const fullSeq = extractLastEventSeq(fullContent);
+        return fullSeq === null ? 0 : fullSeq + 1;
     }
     catch {
         return 0;
@@ -487,8 +546,8 @@ export async function appendEvent(specDir, input) {
     const eventsPath = getSessionEventsPath(specDir, input.session_id);
     // Ensure session directory exists (lazy creation)
     await fsPromises.mkdir(sessionDir, { recursive: true });
-    // Get current event count for seq assignment
-    const seq = input.seq ?? (await getEventCount(specDir, input.session_id));
+    // Derive next sequence number from the last stored event.
+    const seq = input.seq ?? (await getNextEventSeq(specDir, input.session_id));
     // Build full event
     const event = {
         ts: input.ts ?? Date.now(),
@@ -765,6 +824,321 @@ export async function getLastEvent(specDir, sessionId) {
     }
     return events[events.length - 1];
 }
+// ─── Stale Session Candidate Selection ──────────────────────────────────────
+const RELATIVE_DURATION_PATTERN = /^(\d+)([hdwm])$/i;
+const STALE_DEFAULTS = {
+    olderThan: "24h",
+    inactiveFor: "6h",
+    livenessGuard: "5m",
+};
+function durationGuidance(flag) {
+    return `--${flag} accepts relative durations only (h, d, w, m), for example 6h, 7d, 2w, 1m`;
+}
+function parseRelativeDurationMs(rawValue) {
+    const match = rawValue.match(RELATIVE_DURATION_PATTERN);
+    if (!match)
+        return null;
+    const amount = parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    if (Number.isNaN(amount))
+        return null;
+    switch (unit) {
+        case "h":
+            return amount * 60 * 60 * 1000;
+        case "d":
+            return amount * 24 * 60 * 60 * 1000;
+        case "w":
+            return amount * 7 * 24 * 60 * 60 * 1000;
+        case "m":
+            return amount * 60 * 1000;
+        default:
+            return null;
+    }
+}
+function parseCriteriaDuration(field, value) {
+    const parsed = parseRelativeDurationMs(value);
+    if (parsed !== null) {
+        return { ok: true, ms: parsed };
+    }
+    const parsedDate = new Date(value);
+    const appearsAbsolute = !Number.isNaN(parsedDate.getTime());
+    return {
+        ok: false,
+        field,
+        value,
+        message: appearsAbsolute
+            ? `Invalid value for --${field}: "${value}" (absolute timestamps are not supported)`
+            : `Invalid value for --${field}: "${value}"`,
+        guidance: durationGuidance(field),
+    };
+}
+export function resolveStaleSessionCriteria(input) {
+    const olderThan = input.olderThan ?? STALE_DEFAULTS.olderThan;
+    const inactiveFor = input.inactiveFor ?? STALE_DEFAULTS.inactiveFor;
+    const livenessGuard = input.livenessGuard ?? STALE_DEFAULTS.livenessGuard;
+    const olderThanParsed = parseCriteriaDuration("older-than", olderThan);
+    if (!olderThanParsed.ok)
+        return olderThanParsed;
+    const olderThanMs = olderThanParsed.ms;
+    const inactiveForParsed = parseCriteriaDuration("inactive-for", inactiveFor);
+    if (!inactiveForParsed.ok)
+        return inactiveForParsed;
+    const inactiveForMs = inactiveForParsed.ms;
+    const livenessGuardParsed = parseCriteriaDuration("liveness-guard", livenessGuard);
+    if (!livenessGuardParsed.ok)
+        return livenessGuardParsed;
+    const livenessGuardMs = livenessGuardParsed.ms;
+    return {
+        ok: true,
+        criteria: {
+            olderThan,
+            olderThanMs,
+            inactiveFor,
+            inactiveForMs,
+            livenessGuard,
+            livenessGuardMs,
+        },
+    };
+}
+/**
+ * Resolve most recent activity timestamp for stale-session candidate checks.
+ *
+ * Unlike readEvents(), this is strict: corrupt events are surfaced as failures
+ * so stale auto-close can skip unsafe sessions.
+ */
+export async function getSessionActivityForStaleCheck(specDir, sessionId) {
+    const metadata = await getSession(specDir, sessionId);
+    if (!metadata) {
+        return {
+            ok: false,
+            reason: "invalid_started_at",
+            detail: `Session metadata missing or unreadable for ${sessionId}`,
+        };
+    }
+    const startedAtTs = new Date(metadata.started_at).getTime();
+    if (Number.isNaN(startedAtTs)) {
+        return {
+            ok: false,
+            reason: "invalid_started_at",
+            detail: `Session ${sessionId} has invalid started_at timestamp`,
+        };
+    }
+    const eventsPath = getSessionEventsPath(specDir, sessionId);
+    let content;
+    try {
+        content = await fsPromises.readFile(eventsPath, "utf-8");
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return {
+                ok: true,
+                activity: {
+                    lastActivityAt: metadata.started_at,
+                    lastActivityTs: startedAtTs,
+                    source: "started_at",
+                },
+            };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            reason: "events_unreadable",
+            detail: `Unable to read events.jsonl for ${sessionId}: ${message}`,
+        };
+    }
+    const lines = content
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length === 0) {
+        return {
+            ok: true,
+            activity: {
+                lastActivityAt: metadata.started_at,
+                lastActivityTs: startedAtTs,
+                source: "started_at",
+            },
+        };
+    }
+    let latestTs = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        try {
+            const parsed = JSON.parse(line);
+            const event = SessionEventSchema.parse(parsed);
+            if (latestTs === null || event.ts > latestTs) {
+                latestTs = event.ts;
+            }
+        }
+        catch {
+            return {
+                ok: false,
+                reason: "events_corrupt",
+                detail: `Corrupt events.jsonl for ${sessionId}: invalid line ${i + 1}`,
+            };
+        }
+    }
+    if (latestTs === null) {
+        return {
+            ok: true,
+            activity: {
+                lastActivityAt: metadata.started_at,
+                lastActivityTs: startedAtTs,
+                source: "started_at",
+            },
+        };
+    }
+    return {
+        ok: true,
+        activity: {
+            lastActivityAt: new Date(latestTs).toISOString(),
+            lastActivityTs: latestTs,
+            source: "event",
+        },
+    };
+}
+export function evaluateStaleSession(startedAt, activity, criteria, nowMs = Date.now()) {
+    const startedAtMs = new Date(startedAt).getTime();
+    const ageMs = nowMs - startedAtMs;
+    const inactivityMs = nowMs - activity.lastActivityTs;
+    const meetsAgeThreshold = ageMs >= criteria.olderThanMs;
+    const meetsInactivityThreshold = inactivityMs >= criteria.inactiveForMs;
+    const blockedByLivenessGuard = inactivityMs < criteria.livenessGuardMs;
+    const eligible = meetsAgeThreshold &&
+        meetsInactivityThreshold &&
+        !blockedByLivenessGuard;
+    return {
+        startedAt,
+        lastActivityAt: activity.lastActivityAt,
+        lastActivitySource: activity.source,
+        ageMs,
+        inactivityMs,
+        meetsAgeThreshold,
+        meetsInactivityThreshold,
+        blockedByLivenessGuard,
+        eligible,
+    };
+}
+export async function selectStaleActiveSessions(specDir, criteriaInput = {}, nowMs = Date.now()) {
+    const criteriaResolved = resolveStaleSessionCriteria(criteriaInput);
+    if (!criteriaResolved.ok) {
+        throw new Error(`${criteriaResolved.message}. ${criteriaResolved.guidance}`);
+    }
+    const criteria = criteriaResolved.criteria;
+    const sessionIds = await listSessions(specDir);
+    const evaluations = [];
+    const candidates = [];
+    const skipped = [];
+    for (const sessionId of sessionIds) {
+        const metadata = await getSession(specDir, sessionId);
+        if (!metadata || metadata.status !== "active")
+            continue;
+        const activityResult = await getSessionActivityForStaleCheck(specDir, sessionId);
+        if (!activityResult.ok) {
+            skipped.push({
+                sessionId,
+                reason: activityResult.reason,
+                detail: activityResult.detail,
+            });
+            continue;
+        }
+        const evaluation = evaluateStaleSession(metadata.started_at, activityResult.activity, criteria, nowMs);
+        const withSessionId = {
+            sessionId,
+            ...evaluation,
+        };
+        evaluations.push(withSessionId);
+        if (withSessionId.eligible) {
+            candidates.push(withSessionId);
+        }
+    }
+    return {
+        criteria,
+        totalActiveSessions: evaluations.length + skipped.length,
+        evaluations,
+        candidates,
+        skipped,
+        skippedCount: skipped.length,
+        failureCount: skipped.length,
+    };
+}
+/**
+ * Build canonical close_reason for stale auto-abandon updates.
+ *
+ * Canonical format:
+ * auto-abandoned:older-than=<duration>,inactive-for=<duration>,liveness-guard=<duration>,last-activity=<iso>
+ */
+export function buildAutoAbandonedCloseReason(criteria, evaluation) {
+    const segments = [
+        `older-than=${criteria.olderThan}`,
+        `inactive-for=${criteria.inactiveFor}`,
+        `liveness-guard=${criteria.livenessGuard}`,
+        `last-activity=${evaluation.lastActivityAt}`,
+    ];
+    return `auto-abandoned:${segments.join(",")}`;
+}
+/**
+ * Apply abandoned metadata to stale session candidates.
+ *
+ * All updates in a single invocation share one ended_at timestamp, which lets
+ * the caller persist and commit the batch atomically with one shadow commit.
+ */
+export async function applyAutoAbandonMetadata(specDir, selection, options) {
+    const dryRun = options?.dryRun === true;
+    const endedAt = new Date(options?.nowMs ?? Date.now()).toISOString();
+    const updates = [];
+    for (const candidate of selection.candidates) {
+        const closeReason = buildAutoAbandonedCloseReason(selection.criteria, candidate);
+        updates.push({
+            sessionId: candidate.sessionId,
+            status: "abandoned",
+            endedAt,
+            closeReason,
+        });
+        if (dryRun)
+            continue;
+        const metadata = await getSession(specDir, candidate.sessionId);
+        if (!metadata)
+            continue;
+        const updated = {
+            ...metadata,
+            status: "abandoned",
+            ended_at: endedAt,
+            close_reason: closeReason,
+        };
+        const metadataPath = getSessionMetadataPath(specDir, candidate.sessionId);
+        const content = YAML.stringify(updated, {
+            indent: 2,
+            lineWidth: 100,
+            sortMapEntries: false,
+        });
+        await fsPromises.writeFile(metadataPath, content, "utf-8");
+    }
+    let shadowCommitted;
+    if (!dryRun && updates.length > 0 && options?.shadowCommitMessage) {
+        shadowCommitted = await shadowAutoCommit(specDir, options.shadowCommitMessage);
+    }
+    return {
+        dryRun,
+        updatedCount: updates.length,
+        updates,
+        shadowCommitted,
+    };
+}
+// ─── Session Log Summaries ───────────────────────────────────────────────────
+/**
+ * Determine session type from metadata for display.
+ * - "invocation": New agent runtime session (has trigger != "legacy" or agent_id)
+ * - "loop": Legacy ralph loop session (no trigger, or trigger === "legacy")
+ *
+ * AC: @session-model-evolution ac-6
+ */
+function resolveSessionType(metadata) {
+    if (metadata.trigger && metadata.trigger !== "legacy") {
+        return "invocation";
+    }
+    return "loop";
+}
 /**
  * Count lines in events.jsonl without parsing JSON.
  * Much faster than readEvents() for large files.
@@ -798,8 +1172,13 @@ async function countIterations(specDir, sessionId) {
  * Count task completions by scanning events for tool calls that invoke
  * `kspec task complete` or `npm run dev -- task complete`.
  *
- * Real sessions record task completions as session.update events with
- * sessionUpdate: "tool_call" and rawInput.command containing the complete command.
+ * Handles multiple adapter formats:
+ * - claude-code-acp: rawInput.command is a string in tool_call_update events
+ * - claude-agent-acp: rawInput.command is a string in tool_call_update events
+ *   (initial tool_call event has empty rawInput {})
+ * - codex-acp: rawInput.command is an array ['/usr/bin/bash', '-lc', 'kspec task complete @ref']
+ *   in tool_call events; actual command is at index 2
+ *
  * We use a fast substring check before JSON parsing for performance.
  */
 async function countTaskCompletions(specDir, sessionId) {
@@ -814,12 +1193,15 @@ async function countTaskCompletions(specDir, sessionId) {
             // Quick substring pre-filter: only parse lines that might contain task complete commands
             if (!line.includes("task complete"))
                 continue;
-            // Must be a tool_call event (session.update with sessionUpdate: "tool_call")
-            if (!line.includes('"tool_call"'))
-                continue;
             try {
                 const event = JSON.parse(line);
-                const command = event?.data?.update?.rawInput?.command;
+                const rawCommand = event?.data?.update?.rawInput?.command;
+                // Normalize: string (claude-*-acp) or array like [bash, -lc, cmd] (codex-acp)
+                const command = typeof rawCommand === "string"
+                    ? rawCommand
+                    : Array.isArray(rawCommand) && rawCommand.length > 0
+                        ? rawCommand[rawCommand.length - 1]
+                        : undefined;
                 if (typeof command === "string" && /\btask complete\b/.test(command)) {
                     count++;
                 }
@@ -861,6 +1243,7 @@ export async function getSessionLogSummary(specDir, sessionId) {
         id: metadata.id,
         status: metadata.status,
         agent_type: metadata.agent_type,
+        session_type: resolveSessionType(metadata),
         started_at: metadata.started_at,
         ended_at: metadata.ended_at,
         duration_ms: durationMs,
@@ -1015,7 +1398,13 @@ function extractTaskTransitions(events) {
     for (const event of events) {
         if (event.type === "session.update") {
             const data = event.data;
-            const command = data?.update?.rawInput?.command;
+            const rawCommand = data?.update?.rawInput?.command;
+            // Normalize: string (claude-*-acp) or array like [bash, -lc, cmd] (codex-acp)
+            const command = typeof rawCommand === "string"
+                ? rawCommand
+                : Array.isArray(rawCommand) && rawCommand.length > 0
+                    ? rawCommand[rawCommand.length - 1]
+                    : undefined;
             if (typeof command === "string") {
                 if (/\btask start\b/.test(command)) {
                     const ref = extractTaskRef(command);
@@ -1194,6 +1583,7 @@ export async function getSessionLogDetail(specDir, sessionId) {
         id: metadata.id,
         status: metadata.status,
         agent_type: metadata.agent_type,
+        session_type: resolveSessionType(metadata),
         task_id: metadata.task_id,
         started_at: metadata.started_at,
         ended_at: metadata.ended_at,
@@ -1232,6 +1622,8 @@ export function computeSessionLogStats(summaries) {
         active: 0,
         completed: 0,
         abandoned: 0,
+        timed_out: 0,
+        failed: 0,
     };
     for (const s of summaries) {
         totalEvents += s.event_count;
@@ -1243,7 +1635,7 @@ export function computeSessionLogStats(summaries) {
     const n = summaries.length;
     // Build status breakdown
     const statusBreakdown = [];
-    for (const status of ["completed", "active", "abandoned"]) {
+    for (const status of ["completed", "active", "abandoned", "timed_out", "failed"]) {
         const count = statusCounts[status] || 0;
         if (count > 0) {
             statusBreakdown.push({