hammadev 0.1.0-alpha.0

package/dist/core/handoff.js

@@ -0,0 +1,530 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import pc from "picocolors";
+import { extractTaskState, getMessageImportance, HANDOFF_SCHEMA_VERSION, } from "./state.js";
+const HANDOFF_TARGET_BYTES = 15 * 1024;
+const HANDOFF_HARD_MAX_BYTES = 20 * 1024;
+const TIMELINE_MAX_ENTRIES = 50;
+const TIMELINE_MAX_ENTRY_CHARS = 800;
+const CLI_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+function assertCliName(value, label) {
+    if (!CLI_NAME.test(value)) {
+        throw new Error(`Invalid ${label} CLI name '${value}'. Use 1-64 letters, numbers, underscores, or hyphens, starting with a letter or number.`);
+    }
+}
+function assertPathWithin(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(".." + path.sep) ||
+        path.isAbsolute(relative)) {
+        throw new Error(`Refusing handoff path outside ${parent}: ${candidate}`);
+    }
+}
+async function assertDirectoryNotSymlink(directory, label) {
+    const stats = await fs.lstat(directory);
+    if (stats.isSymbolicLink()) {
+        throw new Error(`Cannot create handoff: ${label} must not be a symbolic link (${directory}).`);
+    }
+    if (!stats.isDirectory()) {
+        throw new Error(`Cannot create handoff: ${label} is not a directory (${directory}).`);
+    }
+}
+async function validateProjectPath(projectPath) {
+    if (!path.isAbsolute(projectPath)) {
+        throw new Error(`Cannot create handoff: projectPath must be absolute (${projectPath}).`);
+    }
+    const resolved = path.resolve(projectPath);
+    try {
+        await assertDirectoryNotSymlink(resolved, "projectPath");
+        const canonical = await fs.realpath(resolved);
+        if (canonical !== resolved) {
+            throw new Error(`Cannot create handoff: projectPath contains symbolic-link components (${projectPath}).`);
+        }
+        return canonical;
+    }
+    catch (error) {
+        if (error.message?.startsWith("Cannot create handoff:"))
+            throw error;
+        throw new Error(`Cannot create handoff: invalid projectPath '${projectPath}': ${error.message}`);
+    }
+}
+async function prepareTasksRoot(projectPath) {
+    const hammaRoot = path.join(projectPath, ".hamma");
+    const tasksRoot = path.join(hammaRoot, "tasks");
+    assertPathWithin(projectPath, tasksRoot);
+    for (const [directory, label] of [
+        [hammaRoot, ".hamma directory"],
+        [tasksRoot, ".hamma/tasks directory"],
+    ]) {
+        try {
+            await fs.mkdir(directory);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw new Error(`Cannot create ${label}: ${error.message}`);
+            }
+        }
+        await assertDirectoryNotSymlink(directory, label);
+    }
+    const canonicalTasksRoot = await fs.realpath(tasksRoot);
+    if (canonicalTasksRoot !== tasksRoot) {
+        throw new Error("Cannot create handoff: .hamma/tasks contains symbolic-link components.");
+    }
+    assertPathWithin(projectPath, canonicalTasksRoot);
+    return canonicalTasksRoot;
+}
+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 t = text.trim();
+    const block = t.split(/\n\s*\n/)[0] ?? t;
+    return truncate(block, max);
+}
+function computeRepoState(projectPath) {
+    const warnings = [];
+    if (!projectPath) {
+        warnings.push("No project path available in session metadata.");
+        return { warnings };
+    }
+    const run = (cmd) => {
+        try {
+            const out = execSync(cmd, {
+                cwd: projectPath,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+                maxBuffer: 4 * 1024 * 1024,
+            }).toString();
+            return out.trim();
+        }
+        catch (err) {
+            warnings.push(`\`${cmd}\` failed: ${err.message?.split("\n")[0] ?? "unknown error"}`);
+            return undefined;
+        }
+    };
+    let gitStatusShort = run("git status --short");
+    if (gitStatusShort !== undefined) {
+        const lines = gitStatusShort.split("\n");
+        if (lines.length > 100) {
+            gitStatusShort = lines.slice(0, 100).join("\n") + `\n… (${lines.length - 100} more)`;
+        }
+    }
+    const gitDiffStat = run("git diff --stat");
+    return { gitStatusShort, gitDiffStat, warnings };
+}
+async function ensureGitignore(projectPath) {
+    const gitignorePath = path.join(projectPath, ".gitignore");
+    const entry = "\n# Hamma local agent handoff artifacts\n.hamma/\n";
+    try {
+        const stats = await fs.lstat(gitignorePath).catch((error) => {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (stats?.isSymbolicLink()) {
+            console.warn(pc.yellow(`Warning: Refusing to update symbolic-link .gitignore: ${gitignorePath}`));
+            return;
+        }
+        const content = await fs.readFile(gitignorePath, "utf8");
+        if (!content.includes(".hamma/")) {
+            await fs.appendFile(gitignorePath, entry, "utf8");
+        }
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            await fs.writeFile(gitignorePath, entry.trimStart(), "utf8");
+        }
+        else {
+            console.warn(pc.yellow(`Warning: Could not check/update .gitignore: ${err.message}`));
+        }
+    }
+}
+function fmtCodeBlock(lang, body, empty = "(none)") {
+    const inner = body && body.length > 0 ? body : empty;
+    return "```" + lang + "\n" + inner + "\n```";
+}
+function taskLine(t) {
+    const id = t.id ? `#${t.id}` : "?";
+    const title = t.title ?? firstParagraph(t.summary, 160);
+    return `- **Task ${id}** — ${truncate(title, 200)}`;
+}
+function buildCurrentStateSummary(state) {
+    const completed = state.tasks.filter((t) => t.status === "completed").map((t) => t.id).filter(Boolean);
+    const remaining = state.tasks.filter((t) => t.status === "remaining").map((t) => t.id).filter(Boolean);
+    const parts = [];
+    if (completed.length > 0) {
+        parts.push(`${completed.length} task${completed.length === 1 ? "" : "s"} completed (${formatIdList(completed)})`);
+    }
+    if (remaining.length > 0) {
+        parts.push(`${remaining.length} task${remaining.length === 1 ? "" : "s"} remaining (${formatIdList(remaining)})`);
+    }
+    const summary = parts.length ? parts.join(". ") + "." : "No task ledger detected.";
+    const status = state.current.latestAssistantStatus
+        ? "\n\nLatest source-agent status:\n> " + truncate(state.current.latestAssistantStatus, 500).replace(/\n/g, "\n> ")
+        : "";
+    return summary + status;
+}
+function formatIdList(ids) {
+    const nums = ids
+        .map((s) => Number(s))
+        .filter((n) => Number.isFinite(n))
+        .sort((a, b) => a - b);
+    if (nums.length === 0)
+        return ids.join(", ");
+    const ranges = [];
+    let start = nums[0];
+    let prev = nums[0];
+    for (let i = 1; i < nums.length; i++) {
+        const n = nums[i];
+        if (n === prev + 1) {
+            prev = n;
+            continue;
+        }
+        ranges.push(start === prev ? `#${start}` : `#${start}–#${prev}`);
+        start = n;
+        prev = n;
+    }
+    ranges.push(start === prev ? `#${start}` : `#${start}–#${prev}`);
+    return ranges.join(", ");
+}
+function renderHandoffMarkdown(state, opts) {
+    const { goal, project, current, tasks, verification, risks, repoState, } = state;
+    const completed = tasks.filter((t) => t.status === "completed");
+    const remaining = tasks.filter((t) => t.status === "remaining" || t.status === "in_progress" || t.status === "blocked");
+    const nextAction = current.nextRecommendedTask ??
+        (remaining[0]
+            ? `Task #${remaining[0].id}: ${truncate(remaining[0].title ?? remaining[0].summary, 200)}`
+            : current.latestUserInstruction ?? "Continue from the source agent's last state.");
+    const sections = [];
+    sections.push(`# Hamma Handoff`);
+    sections.push(`## Continue from here\n${truncate(nextAction, 500)}`);
+    sections.push(`## Current state\n${buildCurrentStateSummary(state)}`);
+    if (goal) {
+        sections.push(`## Original goal\n> ${truncate(goal, 400).replace(/\n/g, "\n> ")}`);
+    }
+    sections.push([
+        `## Source`,
+        `- Source CLI: ${project.sourceCli}`,
+        `- Target CLI: ${project.targetCli}`,
+        `- Artifact schema version: ${HANDOFF_SCHEMA_VERSION}`,
+        `- Source session ID: ${project.sourceSessionId ?? "unknown"}`,
+        `- Project path: ${project.path ?? "unknown"}`,
+        `- Source rollout path: ${project.sourcePath ?? "unknown"}`,
+        `- Started at: ${project.startedAt ?? "unknown"}`,
+        `- Last updated: ${project.lastUpdatedAt ?? "unknown"}`,
+    ].join("\n"));
+    const completedBlock = completed.length
+        ? completed.map((t) => taskLine(t)).join("\n")
+        : "(none detected)";
+    sections.push(`## Completed work\n${completedBlock}`);
+    const remainingBlock = remaining.length
+        ? remaining.map((t) => taskLine(t)).join("\n")
+        : current.latestUserInstruction
+            ? `- ${truncate(current.latestUserInstruction, 240)}`
+            : "(none detected)";
+    sections.push(`## Remaining work\n${remainingBlock}`);
+    const verificationList = verification.slice(0, opts.compact ? 8 : 16);
+    const verificationBlock = verificationList.length
+        ? verificationList.map((v) => `- ${v}`).join("\n")
+        : "(no explicit verification signals extracted)";
+    sections.push(`## Verification\n${verificationBlock}`);
+    const gitBlock = [
+        `### \`git status --short\``,
+        fmtCodeBlock("", repoState.gitStatusShort, "(clean)"),
+        `### \`git diff --stat\``,
+        fmtCodeBlock("", repoState.gitDiffStat, "(no unstaged changes)"),
+    ];
+    if (repoState.warnings.length) {
+        gitBlock.push(`Warnings:\n${repoState.warnings.map((w) => `- ${w}`).join("\n")}`);
+    }
+    sections.push(`## Current repo state\n${gitBlock.join("\n")}`);
+    const riskList = risks.slice(0, opts.compact ? 8 : 20);
+    const risksBlock = riskList.length ? riskList.map((r) => `- ${r}`).join("\n") : "(none detected)";
+    sections.push(`## Known risks\n${risksBlock}`);
+    sections.push([
+        `## Safety notes`,
+        `- Sensitive values may have been redacted.`,
+        `- Internal/system/developer context was omitted from the handoff.`,
+        `- Native CLI session files were not modified.`,
+    ].join("\n"));
+    sections.push([
+        `## References`,
+        `- Full normalized session: session.json`,
+        `- Structured state: state.json`,
+        `- Compact timeline: timeline.md`,
+        `- Command summary: commands.md`,
+        `- Redaction report: redaction-report.md`,
+    ].join("\n"));
+    return sections.join("\n\n") + "\n";
+}
+function classifyTimelineImportance(msg) {
+    return getMessageImportance(msg);
+}
+function renderTimelineMarkdown(session) {
+    const messages = session.messages.filter((m) => m.role !== "system");
+    const entries = messages.map((m) => ({
+        timestamp: m.timestamp,
+        role: m.role,
+        content: truncate(firstParagraph(m.content, TIMELINE_MAX_ENTRY_CHARS), TIMELINE_MAX_ENTRY_CHARS),
+        importance: classifyTimelineImportance(m),
+    }));
+    const kept = entries.filter((e) => e.importance !== "low");
+    let selected = kept;
+    let dropped = entries.length - kept.length;
+    if (selected.length > TIMELINE_MAX_ENTRIES) {
+        dropped += selected.length - TIMELINE_MAX_ENTRIES;
+        const high = selected.filter((e) => e.importance === "high");
+        if (high.length <= TIMELINE_MAX_ENTRIES) {
+            const mediums = selected.filter((e) => e.importance === "medium");
+            const room = TIMELINE_MAX_ENTRIES - high.length;
+            const mediumTail = mediums.slice(-room);
+            const mediumSet = new Set(mediumTail);
+            selected = selected.filter((e) => e.importance === "high" || mediumSet.has(e));
+        }
+        else {
+            selected = high.slice(-TIMELINE_MAX_ENTRIES);
+        }
+    }
+    const body = selected
+        .map((e) => {
+        const ts = e.timestamp ?? "unknown-time";
+        const role = e.role.toUpperCase();
+        return `### ${role} — ${ts}\n${e.content}`;
+    })
+        .join("\n\n");
+    const footer = dropped > 0
+        ? `\n\n---\n\n${dropped} lower-importance events omitted. See session.json for full archive.\n`
+        : "\n";
+    return `# Timeline\n\n${body}${footer}`;
+}
+function extractExecCmd(raw) {
+    const m = raw.match(/exec_command\(\s*\{[\s\S]*?\bcmd\s*:\s*"((?:[^"\\]|\\.)*)"/);
+    if (!m)
+        return undefined;
+    return m[1].replace(/\\"/g, '"').replace(/\\\\/g, "\\").replace(/\\n/g, "\n");
+}
+function classifyShell(inner) {
+    let trimmed = inner.trim();
+    while (/^[A-Z_][A-Z0-9_]*=\S+\s+/.test(trimmed) ||
+        /^\S*\[REDACTED_SECRET\]\S*\s+/.test(trimmed)) {
+        trimmed = trimmed.replace(/^\S+\s+/, "");
+    }
+    const tokens = trimmed.split(/\s+/);
+    const first = tokens[0] ?? "";
+    const firstTwo = tokens.slice(0, 2).join(" ");
+    const firstThree = tokens.slice(0, 3).join(" ");
+    if (/^(npm|pnpm|yarn)$/.test(first)) {
+        return { label: firstThree || firstTwo, category: "verification", count: 0 };
+    }
+    if (first === "npx") {
+        return { label: firstThree || firstTwo, category: "verification", count: 0 };
+    }
+    if (first === "git") {
+        return { label: firstTwo, category: "repo", count: 0 };
+    }
+    if (/^(rg|grep|ag|ack|find|ls|sed|awk|cat|head|tail|wc|jq)$/.test(first)) {
+        return { label: first, category: "repo", count: 0, note: "repo inspection" };
+    }
+    if (first === "node" || first === "tsx" || first === "ts-node") {
+        return { label: firstTwo, category: "other", count: 0 };
+    }
+    return { label: first || "shell", category: "other", count: 0 };
+}
+function classifyCommand(raw) {
+    const shellInner = extractExecCmd(raw);
+    if (shellInner)
+        return classifyShell(shellInner);
+    const mcpPlaywright = raw.match(/tools\.mcp__playwright__([a-zA-Z_]+)/);
+    if (mcpPlaywright) {
+        return { label: `playwright.${mcpPlaywright[1]}`, category: "browser", count: 0 };
+    }
+    const mcpOther = raw.match(/tools\.mcp__([a-zA-Z_]+)__([a-zA-Z_]+)/);
+    if (mcpOther) {
+        return { label: `mcp.${mcpOther[1]}.${mcpOther[2]}`, category: "wrapper", count: 0 };
+    }
+    const toolCall = raw.match(/tools\.([a-zA-Z_]+)/);
+    if (toolCall) {
+        return { label: `tools.${toolCall[1]}`, category: "wrapper", count: 0 };
+    }
+    const first = raw.trim().split(/\s+/)[0] ?? "unknown";
+    return { label: first, category: "other", count: 0 };
+}
+function summarizeOutcome(cmd) {
+    if (typeof cmd.exitCode === "number")
+        return `exit ${cmd.exitCode}`;
+    if (!cmd.output)
+        return undefined;
+    const m = cmd.output.match(/"exit_code"\s*:\s*(-?\d+)/);
+    if (m)
+        return `exit ${m[1]}`;
+    return undefined;
+}
+function renderCommandsMarkdown(session) {
+    const buckets = new Map();
+    for (const cmd of session.shellCommands) {
+        const bucket = classifyCommand(cmd.command);
+        const key = `${bucket.category}::${bucket.label}`;
+        const existing = buckets.get(key) ?? { ...bucket };
+        existing.count += 1;
+        const outcome = summarizeOutcome(cmd);
+        if (outcome)
+            existing.latestOutcome = outcome;
+        buckets.set(key, existing);
+    }
+    const all = Array.from(buckets.values()).sort((a, b) => b.count - a.count);
+    const byCategory = {
+        verification: [],
+        repo: [],
+        browser: [],
+        other: [],
+        wrapper: [],
+    };
+    for (const b of all)
+        byCategory[b.category].push(b);
+    const section = (title, items) => {
+        if (items.length === 0)
+            return "";
+        const lines = items.map((b) => {
+            const outcome = b.latestOutcome ? ` — latest: ${b.latestOutcome}` : "";
+            const note = b.note ? ` (${b.note})` : "";
+            return `- \`${b.label}\` — ${b.count}×${outcome}${note}`;
+        });
+        return `## ${title}\n${lines.join("\n")}`;
+    };
+    const parts = [
+        `# Commands`,
+        `Total observed shell/tool invocations: ${session.shellCommands.length}.`,
+        section("Verification & build", byCategory.verification),
+        section("Repo inspection", byCategory.repo),
+        section("Browser / Playwright verification", byCategory.browser),
+        section("Other shell", byCategory.other),
+        section("Wrapper calls (down-ranked)", byCategory.wrapper),
+        `\n> Raw outputs and per-invocation details are omitted from this summary. See session.json for full archive.`,
+    ].filter(Boolean);
+    return parts.join("\n\n") + "\n";
+}
+function renderRedactionReport(session) {
+    return [
+        "# Redaction Report",
+        `Total redactions: ${session.security.redactionCount}`,
+        `Has redactions: ${session.security.redacted}`,
+        "",
+        "Warnings:",
+        ...(session.security.warnings.length
+            ? session.security.warnings.map((w) => `- ${w}`)
+            : ["- None"]),
+        "",
+    ].join("\n");
+}
+function toCompactState(state) {
+    const trimTask = (t) => ({
+        id: t.id,
+        title: t.title,
+        status: t.status,
+        summary: truncate(t.title ?? t.summary, 200),
+        evidence: [],
+        risks: t.risks.slice(0, 1),
+        filesMentioned: t.filesMentioned.slice(0, 2),
+    });
+    return {
+        ...state,
+        tasks: state.tasks.map(trimTask),
+        verification: state.verification.slice(0, 6),
+        risks: state.risks.slice(0, 6),
+        filesMentioned: state.filesMentioned.slice(0, 10),
+    };
+}
+function renderHandoffWithSizeGuard(state) {
+    let md = renderHandoffMarkdown(state, { compact: false });
+    if (Buffer.byteLength(md, "utf8") <= HANDOFF_TARGET_BYTES)
+        return md;
+    md = renderHandoffMarkdown(state, { compact: true });
+    if (Buffer.byteLength(md, "utf8") <= HANDOFF_TARGET_BYTES)
+        return md;
+    md = renderHandoffMarkdown(toCompactState(state), { compact: true });
+    if (Buffer.byteLength(md, "utf8") <= HANDOFF_HARD_MAX_BYTES)
+        return md;
+    const cap = HANDOFF_HARD_MAX_BYTES - 400;
+    const buf = Buffer.from(md, "utf8");
+    if (buf.byteLength <= cap)
+        return md;
+    const truncated = buf.slice(0, cap).toString("utf8");
+    return truncated + "\n\n> Content truncated to respect handoff size limit. See timeline.md and state.json for the full picture.\n";
+}
+export async function createHandoff(session, targetCli, useGitignore = true) {
+    if (!session.meta.projectPath) {
+        throw new Error("Cannot create handoff: source session has no projectPath.");
+    }
+    assertCliName(targetCli, "target");
+    assertCliName(session.meta.sourceCli, "source");
+    const projectPath = await validateProjectPath(session.meta.projectPath);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const taskId = `${timestamp}-${session.meta.sourceCli}-to-${targetCli}`;
+    const tasksRoot = await prepareTasksRoot(projectPath);
+    const finalDir = path.join(tasksRoot, taskId);
+    const tempDir = path.join(tasksRoot, `.tmp-${taskId}`);
+    assertPathWithin(tasksRoot, finalDir);
+    assertPathWithin(tasksRoot, tempDir);
+    if (useGitignore) {
+        await ensureGitignore(projectPath);
+    }
+    const repoState = computeRepoState(projectPath);
+    const state = extractTaskState(session, { targetCli, repoState });
+    let tempCreated = false;
+    try {
+        try {
+            await fs.lstat(finalDir);
+            throw new Error(`Handoff task directory already exists: ${finalDir}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        try {
+            await fs.mkdir(tempDir);
+            tempCreated = true;
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                throw new Error(`Temporary handoff directory already exists; remove it before retrying: ${tempDir}`);
+            }
+            throw error;
+        }
+        await fs.writeFile(path.join(tempDir, "session.json"), JSON.stringify(session, null, 2), "utf8");
+        await fs.writeFile(path.join(tempDir, "state.json"), JSON.stringify(state, null, 2), "utf8");
+        await fs.writeFile(path.join(tempDir, "redaction-report.md"), renderRedactionReport(session), "utf8");
+        await fs.writeFile(path.join(tempDir, "timeline.md"), renderTimelineMarkdown(session), "utf8");
+        await fs.writeFile(path.join(tempDir, "commands.md"), renderCommandsMarkdown(session), "utf8");
+        await fs.writeFile(path.join(tempDir, "handoff.md"), renderHandoffWithSizeGuard(state), "utf8");
+        await fs.rename(tempDir, finalDir);
+        tempCreated = false;
+    }
+    catch (error) {
+        if (tempCreated) {
+            await fs
+                .rm(tempDir, { recursive: true, force: true })
+                .catch(() => undefined);
+        }
+        if (error.code === "EEXIST" || error.code === "ENOTEMPTY") {
+            throw new Error(`Handoff task directory already exists: ${finalDir}`);
+        }
+        throw error;
+    }
+    const handoffPath = path.join(finalDir, "handoff.md");
+    const relativeHandoffPath = path.relative(projectPath, handoffPath);
+    const relTaskDir = path.dirname(relativeHandoffPath);
+    console.log(pc.green("Handoff created at:"));
+    console.log(pc.dim(`Absolute: ${handoffPath}`));
+    console.log(pc.dim(`Relative: ${relativeHandoffPath}`));
+    console.log("");
+    console.log(pc.bold("Suggested command:"));
+    console.log(pc.cyan(`cd ${projectPath}`));
+    console.log(pc.cyan(`${targetCli} "Read ${relTaskDir}/handoff.md and continue the task from the current repo state."`));
+}

package/dist/core/history.js

@@ -0,0 +1,117 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const TASK_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})(?:-(\d{3}))?Z(?:-|$)/;
+function timestampFromTaskId(taskId) {
+    const match = taskId.match(TASK_TIMESTAMP);
+    if (!match)
+        return undefined;
+    const [, year, month, day, hour, minute, second, millis = "000"] = match;
+    const date = new Date(`${year}-${month}-${day}T${hour}:${minute}:${second}.${millis}Z`);
+    return Number.isNaN(date.getTime()) ? undefined : date;
+}
+function field(markdown, label) {
+    const match = markdown.match(new RegExp(`^- ${label}:\\s*(.+)$`, "mi"));
+    return match?.[1]?.trim();
+}
+function continueFromHere(markdown) {
+    const match = markdown.match(/^## Continue from here\s*\n+([\s\S]*?)(?=\n##\s|$)/mi);
+    if (!match)
+        return undefined;
+    const line = match[1]
+        .split("\n")
+        .map((value) => value.trim())
+        .find(Boolean);
+    return line || undefined;
+}
+function tasksPath(projectPath) {
+    return path.join(path.resolve(projectPath), ".hamma", "tasks");
+}
+function assertTaskId(taskId) {
+    if (!taskId ||
+        taskId === "." ||
+        taskId === ".." ||
+        path.basename(taskId) !== taskId ||
+        taskId.includes("/") ||
+        taskId.includes("\\")) {
+        throw new Error(`Invalid handoff task id: ${taskId}`);
+    }
+}
+export async function listHandoffs(projectPath) {
+    const root = tasksPath(projectPath);
+    let entries;
+    try {
+        entries = await fs.readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const handoffs = await Promise.all(entries
+        .filter((entry) => entry.isDirectory())
+        .map(async (entry) => {
+        const handoffPath = path.join(root, entry.name, "handoff.md");
+        try {
+            const [markdown, stats] = await Promise.all([
+                fs.readFile(handoffPath, "utf8"),
+                fs.stat(path.join(root, entry.name)),
+            ]);
+            const created = timestampFromTaskId(entry.name) ?? stats.birthtime ?? stats.mtime;
+            return {
+                taskId: entry.name,
+                sourceAgent: field(markdown, "Source CLI") ?? "unknown",
+                targetAgent: field(markdown, "Target CLI") ?? "unknown",
+                createdAt: created.toISOString(),
+                handoffPath,
+                continueFromHere: continueFromHere(markdown),
+            };
+        }
+        catch (error) {
+            if (error.code === "ENOENT" || error.code === "EISDIR")
+                return undefined;
+            throw error;
+        }
+    }));
+    return handoffs
+        .filter((entry) => entry !== undefined)
+        .sort((a, b) => {
+        const byTime = Date.parse(b.createdAt) - Date.parse(a.createdAt);
+        return byTime || b.taskId.localeCompare(a.taskId);
+    });
+}
+export async function readHandoff(projectPath, taskId) {
+    const resolvedTaskId = taskId === "latest"
+        ? (await listHandoffs(projectPath))[0]?.taskId
+        : taskId;
+    if (!resolvedTaskId) {
+        throw new Error(`No handoffs found in ${tasksPath(projectPath)}.`);
+    }
+    assertTaskId(resolvedTaskId);
+    const handoffPath = path.join(tasksPath(projectPath), resolvedTaskId, "handoff.md");
+    try {
+        return await fs.readFile(handoffPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Handoff '${resolvedTaskId}' was not found in ${tasksPath(projectPath)}.`);
+        }
+        throw error;
+    }
+}
+export function formatHandoffLog(entries) {
+    return entries
+        .map((entry) => {
+        const lines = [
+            `Task: ${entry.taskId}`,
+            `  Source agent: ${entry.sourceAgent}`,
+            `  Target agent: ${entry.targetAgent}`,
+            `  Created: ${entry.createdAt}`,
+            `  Handoff: ${entry.handoffPath}`,
+        ];
+        if (entry.continueFromHere) {
+            lines.push(`  Continue from here: ${entry.continueFromHere}`);
+        }
+        return lines.join("\n");
+    })
+        .join("\n\n");
+}