hammadev 0.1.0-alpha.0

package/dist/core/project-status.js

@@ -0,0 +1,167 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { discoverClaudeSessions } from "../adapters/claude/discover.js";
+import { discoverCodexSessions } from "../adapters/codex/discover.js";
+import { listHandoffs } from "./history.js";
+const execFileAsync = promisify(execFile);
+function safeMetadata(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const sanitized = value.replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+    return sanitized ? sanitized.slice(0, 80) : undefined;
+}
+async function inspectGit(projectPath) {
+    try {
+        const repository = await execFileAsync("git", ["-C", projectPath, "rev-parse", "--is-inside-work-tree"], {
+            encoding: "utf8",
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        });
+        if (repository.stdout.trim() !== "true") {
+            return {
+                isGitRepo: false,
+                gitStatus: "not-a-repository",
+                hammaIgnored: null,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            isGitRepo: false,
+            gitStatus: error.code === "ENOENT" ? "unavailable" : "not-a-repository",
+            hammaIgnored: null,
+        };
+    }
+    let gitStatus = "unavailable";
+    try {
+        const status = await execFileAsync("git", ["-C", projectPath, "status", "--porcelain"], {
+            encoding: "utf8",
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        });
+        gitStatus = status.stdout.trim() ? "dirty" : "clean";
+    }
+    catch {
+        // Keep the explicit unavailable state when status cannot be read.
+    }
+    let hammaIgnored = false;
+    try {
+        await execFileAsync("git", [
+            "-C",
+            projectPath,
+            "check-ignore",
+            "-q",
+            "--no-index",
+            "--",
+            ".hamma/status-probe",
+        ], {
+            encoding: "utf8",
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        });
+        hammaIgnored = true;
+    }
+    catch (error) {
+        if (error.code !== 1)
+            hammaIgnored = false;
+    }
+    return { isGitRepo: true, gitStatus, hammaIgnored };
+}
+async function countTaskDirectories(projectPath) {
+    const tasksPath = path.join(projectPath, ".hamma", "tasks");
+    try {
+        const entries = await fs.readdir(tasksPath, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".tmp-")).length;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+}
+async function routeFromState(latest) {
+    try {
+        const statePath = path.join(path.dirname(latest.handoffPath), "state.json");
+        const state = JSON.parse(await fs.readFile(statePath, "utf8"));
+        return {
+            sourceAgent: safeMetadata(state?.project?.sourceCli ?? state?.sourceCli),
+            targetAgent: safeMetadata(state?.project?.targetCli ?? state?.targetCli),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+async function latestHandoffStatus(handoffs) {
+    const latest = handoffs[0];
+    if (!latest)
+        return undefined;
+    const stateRoute = latest.sourceAgent === "unknown" || latest.targetAgent === "unknown"
+        ? await routeFromState(latest)
+        : {};
+    return {
+        taskId: latest.taskId,
+        path: latest.handoffPath,
+        sourceAgent: safeMetadata(latest.sourceAgent) === "unknown"
+            ? stateRoute.sourceAgent
+            : safeMetadata(latest.sourceAgent),
+        targetAgent: safeMetadata(latest.targetAgent) === "unknown"
+            ? stateRoute.targetAgent
+            : safeMetadata(latest.targetAgent),
+    };
+}
+export async function getProjectStatus(projectPath, options = {}) {
+    const resolvedProjectPath = path.resolve(projectPath);
+    let stats;
+    try {
+        stats = await fs.stat(resolvedProjectPath);
+    }
+    catch (error) {
+        throw new Error(`Cannot inspect project '${resolvedProjectPath}': ${error.message}`);
+    }
+    if (!stats.isDirectory()) {
+        throw new Error(`Project path is not a directory: ${resolvedProjectPath}`);
+    }
+    const [git, handoffCount, handoffs, codexSessions, claudeSessions] = await Promise.all([
+        inspectGit(resolvedProjectPath),
+        countTaskDirectories(resolvedProjectPath),
+        listHandoffs(resolvedProjectPath),
+        discoverCodexSessions(options.codexHome),
+        discoverClaudeSessions(options.claudeHomes),
+    ]);
+    return {
+        projectPath: resolvedProjectPath,
+        isGitRepo: git.isGitRepo,
+        gitStatus: git.gitStatus,
+        handoffCount,
+        latestHandoff: await latestHandoffStatus(handoffs),
+        codexSessionCount: codexSessions.length,
+        claudeSessionCount: claudeSessions.length,
+        hammaIgnored: git.hammaIgnored,
+    };
+}
+function yesNo(value) {
+    return value ? "yes" : "no";
+}
+export function formatProjectStatus(status) {
+    const latest = status.latestHandoff;
+    const route = latest?.sourceAgent && latest.targetAgent
+        ? `${latest.sourceAgent} → ${latest.targetAgent}`
+        : "unknown";
+    const ignored = status.hammaIgnored === null
+        ? status.gitStatus === "unavailable"
+            ? "n/a (git unavailable)"
+            : "n/a (not a git repository)"
+        : yesNo(status.hammaIgnored);
+    return [
+        `Project: ${status.projectPath}`,
+        `Git repository: ${yesNo(status.isGitRepo)}`,
+        `Git status: ${status.gitStatus}`,
+        `.hamma/tasks count: ${status.handoffCount}`,
+        `Latest handoff id: ${latest?.taskId ?? "none"}`,
+        `Latest handoff path: ${latest?.path ?? "none"}`,
+        `Latest source → target: ${latest ? route : "none"}`,
+        `Codex sessions: ${status.codexSessionCount}`,
+        `Claude sessions: ${status.claudeSessionCount}`,
+        `.hamma/ ignored: ${ignored}`,
+    ].join("\n");
+}

package/dist/core/redact.js

@@ -0,0 +1,21 @@
+const SECRET_PATTERNS = [
+    /sk-[A-Za-z0-9_-]{20,}/g,
+    /sk-proj-[A-Za-z0-9_-]{20,}/g,
+    /sk-ant-[A-Za-z0-9_-]{20,}/g,
+    /ghp_[A-Za-z0-9_]{20,}/g,
+    /github_pat_[A-Za-z0-9_]{20,}/g,
+    /AIza[0-9A-Za-z_-]{20,}/g,
+    /xox[baprs]-[A-Za-z0-9-]{20,}/g,
+    /(api[_-]?key|token|secret|password)\s*[:=]\s*['"]?[^'"\s]+/gi
+];
+export function redactText(input) {
+    let text = input;
+    let count = 0;
+    for (const pattern of SECRET_PATTERNS) {
+        text = text.replace(pattern, () => {
+            count += 1;
+            return "[REDACTED_SECRET]";
+        });
+    }
+    return { text, count };
+}

package/dist/core/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/core/state.js

@@ -0,0 +1,444 @@
+export const HANDOFF_SCHEMA_VERSION = 1;
+const IMPORTANT_USER_WORDS = /\b(audit|assess|fix|build|implement|proceed|resume|continue|task|verify|use mcp|minimize|do not)\b/i;
+const COMPLETED_PATTERNS = [
+    /Task #?(\d+)\s+completed/gi,
+    /Task #?(\d+)\s+fixed/gi,
+    /Fixed finding #?(\d+)/gi,
+];
+const REMAINING_PATTERNS = [
+    /Next is task #?(\d+)(?::\s*([^\n.]+))?/gi,
+    /Remaining[^\n.]*task #?(\d+)(?::\s*([^\n.]+))?/gi,
+    /task #?(\d+)\s+remains/gi,
+];
+const LATEST_STATUS_MARKER = /\b(?:task #?\d+ (?:completed|fixed)|fixed finding #?\d+|completed|passes|remaining|next is task)\b/i;
+const VERIFICATION_CATEGORIES = [
+    {
+        name: "Typecheck",
+        verb: "passes",
+        patterns: [/\btypecheck[^\n]*(?:passes|passed|clean|ok|no errors)/i, /\btsc[^\n]*(?:passes|passed|clean|no errors)/i],
+    },
+    {
+        name: "Production build",
+        verb: "passes",
+        patterns: [/production build[^\n]*(?:passes|passed|clean|succeed)/i, /\bbuild passes\b/i, /\bnpm run build\b[^\n]*(?:passes|passed|clean|succeed|success)/i],
+    },
+    {
+        name: "Targeted ESLint",
+        verb: "passes",
+        patterns: [
+            /targeted eslint/i,
+            /\beslint\b[^\n]*(?:passes|passed|0 errors|no errors|clean)/i,
+            /\blint\b[^\n]*(?:passes|passed|clean|0 errors)/i,
+        ],
+    },
+    {
+        name: "Tests",
+        verb: "pass",
+        patterns: [/tests?:\s*\d+\/\d+/i, /\b\d+\/\d+\s*(?:tests?\s*)?pass/i, /\ball tests pass\b/i],
+    },
+    {
+        name: "Browser/Playwright checks",
+        verb: "verified",
+        patterns: [/browser-tested/i, /\bplaywright\b[^\n]*(?:verified|passes|passed|checks?)/i, /playwright mcp/i, /browser mcp/i],
+    },
+];
+const RISK_SIGNALS = [
+    /\bpre-existing\b/i,
+    /\bstill\s+(?:has|have|failing|failing?)\b/i,
+    /\bfailed\b/i,
+    /\bblocked\b/i,
+    /\bregression risk\b/i,
+    /unrelated worktree changes/i,
+    /\bknown (?:issue|risk|failure|bug)\b/i,
+    /\bcaveat\b/i,
+];
+const RISK_NEGATION_SIGNALS = [
+    /\bnow passes\b/i,
+    /\bpasses both\b/i,
+    /\bpassed both\b/i,
+    /\ball green\b/i,
+    /\bno more\b/i,
+    /\bno longer\b/i,
+    /\bnow (?:fixed|resolved|cleared|clean)\b/i,
+    /added [^\n]*?(?:test|regression|coverage)/i,
+];
+export function isImportantUserMessage(content) {
+    return IMPORTANT_USER_WORDS.test(content);
+}
+export function getMessageImportance(msg) {
+    if (msg.role === "system")
+        return "low";
+    if (msg.role === "user") {
+        return isImportantUserMessage(msg.content) ? "high" : "medium";
+    }
+    const c = msg.content;
+    if (COMPLETED_PATTERNS.some((p) => new RegExp(p.source, p.flags.replace("g", "")).test(c)) ||
+        REMAINING_PATTERNS.some((p) => new RegExp(p.source, p.flags.replace("g", "")).test(c)) ||
+        VERIFICATION_CATEGORIES.some((cat) => cat.patterns.some((p) => p.test(c))) ||
+        /\bnext is task\b/i.test(c) ||
+        /\bfixed finding\b/i.test(c)) {
+        return "high";
+    }
+    if (RISK_SIGNALS.some((p) => p.test(c)))
+        return "medium";
+    return "low";
+}
+function truncate(s, max) {
+    if (!s)
+        return "";
+    const t = s.trim();
+    if (t.length <= max)
+        return t;
+    return t.slice(0, max).trimEnd() + "…";
+}
+function firstParagraph(text, max) {
+    const cleaned = text.trim();
+    const block = cleaned.split(/\n\s*\n/)[0] ?? cleaned;
+    return truncate(block, max);
+}
+function mergeUnique(a, b) {
+    const s = new Set();
+    for (const x of a)
+        if (x)
+            s.add(x);
+    for (const x of b)
+        if (x)
+            s.add(x);
+    return Array.from(s);
+}
+function stripLineCol(p) {
+    return p.replace(/:\d+(?::\d+)?$/, "");
+}
+function stripTrailingPunct(p) {
+    return p.replace(/[)\],.:;!?'"`>]+$/, "");
+}
+export function extractFilePaths(text) {
+    const found = new Set();
+    const dirRe = /(?:^|[\s`"'([\]<>])((?:[/A-Za-z0-9_.-]+)?(?:src|app|components|lib|pages|public|scripts|tests?|hooks|utils|styles|content|config|api|server|packages)\/[A-Za-z0-9_\-./]+\.[A-Za-z0-9]+(?::\d+(?::\d+)?)?)/g;
+    for (const m of text.matchAll(dirRe)) {
+        let p = stripTrailingPunct(m[1]);
+        p = stripLineCol(p);
+        if (p.length >= 3 && p.length <= 300)
+            found.add(p);
+    }
+    const extRe = /(?:^|[\s`"'([\]<>/])([A-Za-z0-9_.-]+\.(?:tsx?|jsx?|css|json|md|ya?ml|html|toml))(?=[\s`"')\]:>,.]|$)/g;
+    for (const m of text.matchAll(extRe)) {
+        const p = stripTrailingPunct(m[1]);
+        if (p.length >= 3 && p.length <= 300 && !/^\.+$/.test(p))
+            found.add(p);
+    }
+    const absRe = /(\/(?:home|Users|root|tmp|var|opt|workspace|srv)\/[A-Za-z0-9_\-./]+(?::\d+(?::\d+)?)?)/g;
+    for (const m of text.matchAll(absRe)) {
+        let p = stripTrailingPunct(m[1]);
+        p = stripLineCol(p);
+        if (/\.[A-Za-z0-9]+$/.test(p) && p.length <= 300)
+            found.add(p);
+    }
+    return Array.from(found);
+}
+function cleanTitle(raw) {
+    let t = raw.replace(/\s+/g, " ").trim();
+    t = t.replace(/^(Critical|High|Medium|Low):\s*/i, "");
+    // Take up to the first sentence-ending punctuation followed by a space and a capital letter
+    const sentenceMatch = t.match(/^([\s\S]+?[.!?])\s+[A-Z]/);
+    if (sentenceMatch && sentenceMatch[1].length >= 10) {
+        t = sentenceMatch[1];
+    }
+    // Strip trailing "See [ref](path)..."
+    t = t.replace(/\s+See\s+\[[^\n]*$/, "");
+    // Strip trailing punctuation
+    t = t.replace(/[:.,;\s]+$/, "");
+    if (t.length === 0)
+        return t;
+    t = t.charAt(0).toUpperCase() + t.slice(1);
+    return t;
+}
+function extractPlanItems(text) {
+    const items = [];
+    const re = /(?:^|\n)\s{0,4}(\d+)\.\s+(.{5,400}?)(?=\n\s{0,4}\d+\.\s|\n\s*\n|$)/gs;
+    for (const m of text.matchAll(re)) {
+        const id = m[1];
+        const title = cleanTitle(m[2]);
+        if (title.length >= 5 && title.length <= 220) {
+            items.push({ id, title });
+        }
+    }
+    return items;
+}
+function buildTitleRegistry(assistants) {
+    const candidates = new Map();
+    let order = 0;
+    const add = (id, rawTitle, priority) => {
+        const title = cleanTitle(rawTitle);
+        if (title.length < 5 || title.length > 220)
+            return;
+        const arr = candidates.get(id) ?? [];
+        arr.push({ title, priority, order: order++ });
+        candidates.set(id, arr);
+    };
+    const introPatterns = [
+        {
+            re: /(?:I(?:'m|['’]m|['’]ve| am)?\s+(?:proceeding|starting|working|treating this as fixing|treating this as|kicking off))\s+(?:with\s+|on\s+|as\s+)?(?:finding|task)\s*#?(\d+):\s*([^\n]{6,300})/gi,
+            priority: 4,
+        },
+        {
+            re: /Next is\s+(?:task|finding)\s*#?(\d+):\s*([^\n]{6,300})/gi,
+            priority: 3,
+        },
+        {
+            re: /Fixed finding\s*#?(\d+):\s*([^\n]{6,300})/gi,
+            priority: 2,
+        },
+    ];
+    for (const msg of assistants) {
+        for (const { re, priority } of introPatterns) {
+            for (const m of msg.content.matchAll(re)) {
+                add(m[1], m[2], priority);
+            }
+        }
+        for (const item of extractPlanItems(msg.content)) {
+            add(item.id, item.title, 1);
+        }
+    }
+    const registry = new Map();
+    for (const [id, list] of candidates) {
+        list.sort((a, b) => b.priority - a.priority || b.order - a.order);
+        registry.set(id, list[0].title);
+    }
+    return registry;
+}
+function splitClauses(text) {
+    const clauses = [];
+    for (const line of text.split(/\n+/)) {
+        const cleaned = line.replace(/^[\s>*\-–—•]+/, "").trim();
+        if (!cleaned)
+            continue;
+        const parts = cleaned.split(/(?<=[.!?])\s+(?=[A-Z"`\[])|;\s+/);
+        for (const part of parts) {
+            const t = part.trim();
+            if (t.length >= 6)
+                clauses.push(t);
+        }
+    }
+    return clauses;
+}
+function isActionableRisk(clause) {
+    const hasRisk = RISK_SIGNALS.some((p) => p.test(clause));
+    if (!hasRisk)
+        return false;
+    const negated = RISK_NEGATION_SIGNALS.some((p) => p.test(clause));
+    return !negated;
+}
+function tokenizeForSimilarity(s) {
+    return new Set(s
+        .toLowerCase()
+        .replace(/[^\w\s]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 3));
+}
+function dedupRisks(risks, maxItems = 8) {
+    const kept = [];
+    for (const raw of risks) {
+        const r = raw.replace(/\s+/g, " ").trim();
+        if (!r)
+            continue;
+        const tr = tokenizeForSimilarity(r);
+        let mergedInto = -1;
+        for (let i = 0; i < kept.length; i++) {
+            const tk = tokenizeForSimilarity(kept[i]);
+            const inter = [...tr].filter((w) => tk.has(w));
+            const smaller = Math.min(tr.size, tk.size);
+            if (smaller > 0 && inter.length / smaller > 0.6) {
+                mergedInto = i;
+                break;
+            }
+        }
+        if (mergedInto === -1) {
+            kept.push(r);
+        }
+        else if (r.length < kept[mergedInto].length) {
+            kept[mergedInto] = r;
+        }
+        if (kept.length >= maxItems)
+            break;
+    }
+    return kept;
+}
+function categorizeVerification(session) {
+    const buckets = VERIFICATION_CATEGORIES.map((c) => ({
+        name: c.name,
+        verb: c.verb,
+        count: 0,
+    }));
+    for (const msg of session.messages) {
+        if (msg.role !== "assistant")
+            continue;
+        for (const rawLine of msg.content.split(/\n/)) {
+            const line = rawLine.replace(/^[\s>*\-–—•]+/, "").trim();
+            if (!line)
+                continue;
+            for (let i = 0; i < VERIFICATION_CATEGORIES.length; i++) {
+                const cat = VERIFICATION_CATEGORIES[i];
+                if (cat.patterns.some((p) => p.test(line))) {
+                    buckets[i].count += 1;
+                    if (cat.name === "Tests") {
+                        const nm = line.match(/(\d+)\/(\d+)/);
+                        if (nm)
+                            buckets[i].lastNumericSample = `${nm[1]}/${nm[2]}`;
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    const results = [];
+    for (const b of buckets) {
+        if (b.count === 0)
+            continue;
+        if (b.name === "Tests" && b.lastNumericSample) {
+            results.push(`Tests: ${b.lastNumericSample} pass (${b.count} confirmation${b.count === 1 ? "" : "s"})`);
+        }
+        else {
+            results.push(`${b.name}: ${b.verb} (${b.count} confirmation${b.count === 1 ? "" : "s"})`);
+        }
+    }
+    return results;
+}
+function collectFileMentions(messages) {
+    const files = new Set();
+    for (const msg of messages) {
+        for (const p of extractFilePaths(msg.content))
+            files.add(p);
+    }
+    return Array.from(files);
+}
+function collectRisks(messages) {
+    const raw = [];
+    for (const msg of messages) {
+        if (msg.role === "system")
+            continue;
+        for (const clause of splitClauses(msg.content)) {
+            if (isActionableRisk(clause)) {
+                raw.push(truncate(clause, 240));
+            }
+        }
+    }
+    return dedupRisks(raw);
+}
+export function extractTaskState(session, options) {
+    const { targetCli, repoState } = options;
+    const messages = session.messages.filter((m) => m.role !== "system");
+    const users = messages.filter((m) => m.role === "user");
+    const assistants = messages.filter((m) => m.role === "assistant");
+    const importantUsers = users.filter((u) => isImportantUserMessage(u.content));
+    const firstUser = users[0];
+    const goalUser = firstUser && firstUser.content.trim().length >= 20 ? firstUser : importantUsers[0] ?? firstUser;
+    const latestImportantUser = importantUsers[importantUsers.length - 1] ?? users[users.length - 1];
+    const latestStatusAssistant = [...assistants].reverse().find((a) => LATEST_STATUS_MARKER.test(a.content)) ??
+        assistants[assistants.length - 1];
+    const titleRegistry = buildTitleRegistry(assistants);
+    const tasksById = new Map();
+    for (const msg of assistants) {
+        for (const pat of COMPLETED_PATTERNS) {
+            for (const mm of msg.content.matchAll(pat)) {
+                const id = mm[1];
+                const files = extractFilePaths(msg.content);
+                const existing = tasksById.get(id);
+                const summary = firstParagraph(msg.content, 400);
+                tasksById.set(id, {
+                    id,
+                    title: titleRegistry.get(id) ?? existing?.title,
+                    status: "completed",
+                    summary: existing?.status === "completed" && existing.summary ? existing.summary : summary,
+                    evidence: mergeUnique(existing?.evidence ?? [], msg.timestamp ? [msg.timestamp] : []),
+                    risks: existing?.risks ?? [],
+                    filesMentioned: mergeUnique(existing?.filesMentioned ?? [], files),
+                });
+            }
+        }
+        for (const pat of REMAINING_PATTERNS) {
+            for (const mm of msg.content.matchAll(pat)) {
+                const id = mm[1];
+                const existing = tasksById.get(id);
+                if (existing && existing.status === "completed")
+                    continue;
+                const files = extractFilePaths(msg.content);
+                tasksById.set(id, {
+                    id,
+                    title: titleRegistry.get(id) ?? existing?.title,
+                    status: "remaining",
+                    summary: existing?.summary || firstParagraph(msg.content, 300),
+                    evidence: mergeUnique(existing?.evidence ?? [], msg.timestamp ? [msg.timestamp] : []),
+                    risks: existing?.risks ?? [],
+                    filesMentioned: mergeUnique(existing?.filesMentioned ?? [], files),
+                });
+            }
+        }
+    }
+    for (const [id, title] of titleRegistry) {
+        if (tasksById.has(id))
+            continue;
+        tasksById.set(id, {
+            id,
+            title,
+            status: "remaining",
+            summary: truncate(title, 300),
+            evidence: [],
+            risks: [],
+            filesMentioned: [],
+        });
+    }
+    const tasks = Array.from(tasksById.values()).sort((a, b) => {
+        const na = Number(a.id ?? 0);
+        const nb = Number(b.id ?? 0);
+        if (Number.isFinite(na) && Number.isFinite(nb))
+            return na - nb;
+        return 0;
+    });
+    const verification = categorizeVerification(session);
+    const risksAgg = collectRisks(messages);
+    const filesAgg = collectFileMentions(messages);
+    const remainingTasks = tasks.filter((t) => t.status === "remaining");
+    let nextRecommended;
+    if (remainingTasks.length > 0) {
+        const t = remainingTasks[0];
+        const label = t.title ?? t.summary;
+        nextRecommended = `Task #${t.id}: ${truncate(label, 220)}`;
+    }
+    else if (latestImportantUser) {
+        nextRecommended = truncate(latestImportantUser.content, 240);
+    }
+    return {
+        schemaVersion: HANDOFF_SCHEMA_VERSION,
+        goal: goalUser ? truncate(goalUser.content, 500) : undefined,
+        project: {
+            path: session.meta.projectPath,
+            sourceCli: session.meta.sourceCli,
+            targetCli,
+            sourceSessionId: session.meta.sourceSessionId,
+            sourcePath: session.meta.sourcePath,
+            startedAt: session.meta.startedAt,
+            lastUpdatedAt: session.meta.lastUpdatedAt,
+        },
+        current: {
+            latestUserInstruction: latestImportantUser
+                ? truncate(latestImportantUser.content, 500)
+                : undefined,
+            latestAssistantStatus: latestStatusAssistant
+                ? truncate(latestStatusAssistant.content, 900)
+                : undefined,
+            nextRecommendedTask: nextRecommended,
+        },
+        tasks,
+        verification,
+        risks: risksAgg,
+        filesMentioned: filesAgg,
+        repoState,
+        references: {
+            fullSession: "session.json",
+            timeline: "timeline.md",
+            commands: "commands.md",
+            redactionReport: "redaction-report.md",
+        },
+    };
+}

package/dist/session-loader.js

@@ -0,0 +1,54 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CodexAdapter } from "./adapters/codex/index.js";
+import { ClaudeAdapter } from "./adapters/claude/index.js";
+import { sessionIdFromFilename } from "./adapters/claude/paths.js";
+async function resolveDirectClaudePath(target) {
+    const absolutePath = path.resolve(target);
+    if (!path.isAbsolute(target) || path.extname(absolutePath) !== ".jsonl") {
+        throw new Error(`Unsupported session target '${target}'. Use codex:<id>, claude:<id>, a Codex rollout path, or an absolute UUID-named Claude session path.`);
+    }
+    const sessionId = sessionIdFromFilename(absolutePath);
+    const fileStem = path.basename(absolutePath, path.extname(absolutePath));
+    if (!sessionId || fileStem !== sessionId) {
+        throw new Error(`Cannot safely identify direct JSONL path as a Claude session: ${absolutePath}`);
+    }
+    try {
+        const stat = await fs.stat(absolutePath);
+        if (!stat.isFile()) {
+            throw new Error(`Claude session path is not a regular file: ${absolutePath}`);
+        }
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error(`Claude session file does not exist: ${absolutePath}`);
+        }
+        throw err;
+    }
+    return absolutePath;
+}
+export async function resolveSessionTarget(target, options = {}) {
+    if (target.startsWith("claude:")) {
+        return {
+            sourceCli: "claude",
+            sessionPath: await ClaudeAdapter.resolve(target, options.claudeHomes)
+        };
+    }
+    if (target.startsWith("codex:") || path.basename(target).startsWith("rollout-")) {
+        return {
+            sourceCli: "codex",
+            sessionPath: await CodexAdapter.resolve(target, options.codexHome)
+        };
+    }
+    return {
+        sourceCli: "claude",
+        sessionPath: await resolveDirectClaudePath(target)
+    };
+}
+export async function loadSession(target, options = {}) {
+    const resolved = await resolveSessionTarget(target, options);
+    if (resolved.sourceCli === "claude") {
+        return ClaudeAdapter.inspect(resolved.sessionPath);
+    }
+    return CodexAdapter.inspect(resolved.sessionPath);
+}