@sunshinelife83/hearth 1.0.0

package/dist/skills.js

@@ -0,0 +1,84 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadSkills, } from "@earendil-works/pi-coding-agent";
+import { expandHomePath, isPathInsideRoot } from "./roots.js";
+const SUBAGENTS_SKILL_NAME = "subagents";
+const SUBAGENTS_SKILL = join(SUBAGENTS_SKILL_NAME, "SKILL.md");
+function bundledSkillsDir() {
+    return fileURLToPath(new URL("../skills", import.meta.url));
+}
+function hasSubagentsSkill(skillDir) {
+    return existsSync(join(skillDir, SUBAGENTS_SKILL));
+}
+export function effectiveSkillPaths(config, cwd) {
+    const bundledSkills = bundledSkillsDir();
+    const defaultPathCandidates = [
+        join(homedir(), ".agents", "skills"),
+        resolve(cwd, ".agents", "skills"),
+        config.hearthSkillsDir,
+        join(config.agentDir, "skills"),
+        config.subagents.enabled && !hasSubagentsSkill(config.hearthSkillsDir)
+            ? bundledSkills
+            : undefined,
+    ];
+    const defaultPaths = defaultPathCandidates.filter((path) => path !== undefined && existsSync(path));
+    const seen = new Set();
+    return [...defaultPaths, ...config.skillPaths]
+        .map((path) => resolveSkillPath(path, cwd))
+        .filter((path) => {
+        if (seen.has(path))
+            return false;
+        seen.add(path);
+        return true;
+    });
+}
+function resolveSkillPath(path, cwd) {
+    return resolve(cwd, expandHomePath(path));
+}
+export function loadWorkspaceSkills(config, cwd) {
+    if (!config.skillsEnabled)
+        return { skills: [], diagnostics: [] };
+    const result = loadSkills({
+        cwd,
+        agentDir: config.agentDir,
+        skillPaths: effectiveSkillPaths(config, cwd),
+        includeDefaults: false,
+    });
+    if (config.subagents.enabled)
+        return result;
+    return {
+        skills: result.skills.filter((skill) => skill.name !== SUBAGENTS_SKILL_NAME),
+        diagnostics: result.diagnostics.filter((diagnostic) => {
+            const collision = diagnostic.collision;
+            return !(collision?.resourceType === "skill" && collision.name === SUBAGENTS_SKILL_NAME);
+        }),
+    };
+}
+export function resolveSkillReadPath(skills, inputPath) {
+    const absolutePath = resolve(expandHomePath(inputPath));
+    for (const skill of skills) {
+        const skillFilePath = resolve(skill.filePath);
+        if (absolutePath === skillFilePath) {
+            return { absolutePath, skill };
+        }
+    }
+    for (const skill of skills) {
+        const baseDir = resolve(skill.baseDir);
+        if (!isPathInsideRoot(absolutePath, baseDir))
+            continue;
+        return { absolutePath, skill };
+    }
+    return undefined;
+}
+export function formatPathForPrompt(path) {
+    const home = resolve(homedir());
+    const resolvedPath = resolve(path);
+    if (resolvedPath === home)
+        return "~";
+    if (resolvedPath.startsWith(`${home}${sep}`)) {
+        return `~/${resolvedPath.slice(home.length + 1).split(sep).join("/")}`;
+    }
+    return resolvedPath.split(sep).join("/");
+}

package/dist/snapshot-manager.js

@@ -0,0 +1,123 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { git, getGitEligibility, safeWorkspaceRefSegment } from "./git.js";
+const SNAPSHOT_REF_PREFIX = "refs/hearth/snapshots";
+const SNAPSHOT_AUTHOR_ENV_BASE = "hearth-snapshot";
+export class SnapshotError extends Error {
+}
+export async function createSnapshot(input) {
+    const eligibility = await getGitEligibility(input.root);
+    if (!eligibility.ok || !eligibility.gitRoot) {
+        throw new SnapshotError(eligibility.message ?? "snapshots require a Git workspace.");
+    }
+    const gitRoot = eligibility.gitRoot;
+    const head = await headCommit(gitRoot);
+    const tempDir = await mkdtemp(join(tmpdir(), "hearth-snapshot-index-"));
+    try {
+        const env = snapshotEnv(join(tempDir, "index"));
+        if (head)
+            await git(gitRoot, ["read-tree", head], { env });
+        await git(gitRoot, ["add", "-A", "--", input.root], { env });
+        const tree = (await git(gitRoot, ["write-tree"], { env })).stdout.trim();
+        const parentArgs = head ? ["-p", head] : [];
+        const commit = (await git(gitRoot, ["commit-tree", tree, ...parentArgs, "-m", `Hearth snapshot: ${input.label}`], { env })).stdout.trim();
+        const createdAt = new Date().toISOString();
+        const ref = snapshotRef(input.workspaceId, createdAt);
+        await git(gitRoot, ["update-ref", ref, commit]);
+        return {
+            snapshotId: commit,
+            ref,
+            label: input.label,
+            createdAt,
+            dirtyBaseline: head ? false : true,
+        };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+export async function listSnapshots(input) {
+    const eligibility = await getGitEligibility(input.root);
+    if (!eligibility.ok || !eligibility.gitRoot)
+        return [];
+    const gitRoot = eligibility.gitRoot;
+    const prefix = `${SNAPSHOT_REF_PREFIX}/${safeWorkspaceRefSegment(input.workspaceId)}/`;
+    const refs = (await git(gitRoot, [
+        "for-each-ref",
+        "--format=%(refname)\t%(objectname)\t%(creatordate:iso-strict)",
+        SNAPSHOT_REF_PREFIX,
+    ])).stdout.trim();
+    if (!refs)
+        return [];
+    const records = [];
+    for (const line of refs.split("\n")) {
+        const [ref, commit, createdAt] = line.split("\t");
+        if (!ref?.startsWith(prefix) || !commit)
+            continue;
+        const message = (await git(gitRoot, ["log", "-1", "--format=%s", commit])).stdout.trim();
+        records.push({
+            snapshotId: commit,
+            ref,
+            label: message.replace(/^Hearth snapshot: /, ""),
+            createdAt: createdAt || "",
+        });
+    }
+    return records.sort((a, b) => b.ref.localeCompare(a.ref));
+}
+export async function rollbackSnapshot(input) {
+    const eligibility = await getGitEligibility(input.root);
+    if (!eligibility.ok || !eligibility.gitRoot) {
+        throw new SnapshotError(eligibility.message ?? "rollback requires a Git workspace.");
+    }
+    const gitRoot = eligibility.gitRoot;
+    const known = await listSnapshots({ root: input.root, workspaceId: input.workspaceId });
+    const target = known.find((record) => record.snapshotId === input.snapshotId);
+    if (!target) {
+        throw new SnapshotError(`Unknown snapshot for this workspace: ${input.snapshotId}`);
+    }
+    const targetTree = (await git(gitRoot, ["rev-parse", "--verify", `${target.snapshotId}^{tree}`])).stdout.trim();
+    const tempDir = await mkdtemp(join(tmpdir(), "hearth-rollback-"));
+    try {
+        const env = snapshotEnv(join(tempDir, "index"));
+        const head = await headCommit(gitRoot);
+        if (head)
+            await git(gitRoot, ["read-tree", head], { env });
+        await git(gitRoot, ["add", "-A", "--", input.root], { env });
+        const currentTree = (await git(gitRoot, ["write-tree"], { env })).stdout.trim();
+        const patch = (await git(gitRoot, ["diff", "--binary", "--no-color", currentTree, targetTree], {
+            maxBuffer: 100 * 1024 * 1024,
+        })).stdout;
+        if (!patch.trim())
+            return { files: 0 };
+        const patchPath = join(tempDir, "rollback.patch");
+        const { writeFile } = await import("node:fs/promises");
+        await writeFile(patchPath, patch, "utf8");
+        await git(gitRoot, ["apply", "--binary", "--whitespace=nowarn", patchPath], {});
+        return { files: patch.split("\n").filter((line) => line.startsWith("diff --git ")).length };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+async function headCommit(gitRoot) {
+    try {
+        return (await git(gitRoot, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"])).stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function snapshotEnv(indexPath) {
+    return {
+        GIT_INDEX_FILE: indexPath,
+        GIT_AUTHOR_NAME: "Hearth",
+        GIT_AUTHOR_EMAIL: `${SNAPSHOT_AUTHOR_ENV_BASE}@users.noreply.local`,
+        GIT_COMMITTER_NAME: "Hearth",
+        GIT_COMMITTER_EMAIL: `${SNAPSHOT_AUTHOR_ENV_BASE}@users.noreply.local`,
+    };
+}
+function snapshotRef(workspaceId, createdAt) {
+    const epoch = Date.parse(createdAt);
+    return `${SNAPSHOT_REF_PREFIX}/${safeWorkspaceRefSegment(workspaceId)}/${Number.isFinite(epoch) ? epoch : Date.now()}`;
+}

package/dist/stdio-server.js

@@ -0,0 +1,80 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { logEvent } from "./logger.js";
+import { ProcessSessionManager } from "./process-sessions.js";
+import { createReviewCheckpointManager } from "./review-checkpoints.js";
+import { buildLocalAgentProviderStatuses, } from "./local-agent-catalog.js";
+import { getLocalAgentProviderAvailabilitySnapshot } from "./local-agent-availability.js";
+import { createWorkspaceStore } from "./workspace-store.js";
+import { WorkspaceRegistry } from "./workspaces.js";
+import { createMcpServer } from "./server.js";
+import { TaskStore } from "./task-store.js";
+import { probeSandboxAdapter, wrapCommandWithSandbox } from "./policy/sandbox.js";
+import { resolveExecutionForWorkspace } from "./policy/workspace-profiles.js";
+export function buildLocalMcpServer(config, options = {}) {
+    const workspaceStore = createWorkspaceStore(config.stateDir);
+    const workspaces = new WorkspaceRegistry(config, workspaceStore);
+    const taskStore = new TaskStore(config.stateDir);
+    taskStore.reconcileOnBoot();
+    const reviewCheckpoints = createReviewCheckpointManager();
+    const processJournalDir = `${config.stateDir}/process-journal`;
+    void import("./process-journal.js").then(({ reapProcessJournal }) => reapProcessJournal(processJournalDir, (event, details) => logEvent(config.logging, "warn", event, details)).catch(() => undefined)).catch(() => undefined);
+    const processSessions = new ProcessSessionManager({
+        environment: {
+            allowAll: config.execution.envAllowAll,
+            extraAllowlist: config.execution.envAllowlist,
+        },
+        journalDir: processJournalDir,
+        ...(config.execution.sandbox === "none" && config.workspaceProfiles.every((profile) => profile.sandbox !== "auto")
+            ? {}
+            : {
+                commandWrapper: (shell, ctx) => {
+                    const resolved = resolveExecutionForWorkspace(config, ctx.workspaceRoot);
+                    return wrapCommandWithSandbox(shell, probeSandboxAdapter(), {
+                        workspaceRoot: ctx.workspaceRoot,
+                        allowNetwork: (resolved.sandboxNetwork ?? config.execution.sandboxNetwork) === "allow",
+                    });
+                },
+            }),
+    });
+    const resolveLocalAgentProviders = () => buildLocalAgentProviderStatuses(config.subagents, getLocalAgentProviderAvailabilitySnapshot());
+    const server = createMcpServer(config, workspaces, reviewCheckpoints, processSessions, resolveLocalAgentProviders, options.incomingArtifactAdapters ?? [], undefined, taskStore);
+    return {
+        server,
+        workspaces,
+        close: async () => {
+            processSessions.shutdown();
+            workspaceStore.close?.();
+            taskStore.close();
+        },
+    };
+}
+/**
+ * Run Hearth as a local stdio MCP server. stdout carries only the MCP
+ * protocol; human-readable logging goes to stderr.
+ */
+export async function runStdioServer(config) {
+    const { server, close } = buildLocalMcpServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logEvent(config.logging, "info", "stdio_server_started", {
+        allowedRoots: config.allowedRoots,
+        mode: config.execution.mode,
+    });
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        void (async () => {
+            try {
+                await server.close();
+            }
+            finally {
+                await close();
+                process.exit(0);
+            }
+        })();
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}

package/dist/task-store.js

@@ -0,0 +1,203 @@
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { openDatabase } from "./db/client.js";
+/** Allowed transitions; anything else is rejected by the state machine. */
+const TRANSITIONS = {
+    planning: ["executing", "cancelled"],
+    executing: ["verifying", "cancelled", "failed"],
+    verifying: ["completed", "repairing", "failed", "cancelled"],
+    repairing: ["verifying", "executing", "cancelled", "failed"],
+    completed: [],
+    failed: [],
+    cancelled: [],
+};
+export class TaskTransitionError extends Error {
+    from;
+    to;
+    constructor(from, to) {
+        super(`Illegal task transition: ${from} → ${to}`);
+        this.from = from;
+        this.to = to;
+        this.name = "TaskTransitionError";
+    }
+}
+export class TaskStore {
+    database;
+    constructor(stateDir) {
+        this.database = openDatabase(stateDir);
+    }
+    create(input) {
+        const now = new Date().toISOString();
+        const record = {
+            id: `task_${randomUUID().replaceAll("-", "").slice(0, 12)}`,
+            workspaceId: input.workspaceId,
+            workspaceRoot: resolve(input.workspaceRoot),
+            goal: input.goal,
+            status: "planning",
+            mode: input.mode ?? "supervised",
+            evidence: [],
+            toolCalls: 0,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.database.sqlite
+            .prepare(`insert into tasks (
+          id, workspace_id, workspace_root, goal, status, completion_state,
+          mode, plan, evidence, error, tool_calls, created_at, updated_at
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(record.id, record.workspaceId ?? null, record.workspaceRoot, record.goal, record.status, null, record.mode, null, JSON.stringify(record.evidence), null, 0, record.createdAt, record.updatedAt);
+        return record;
+    }
+    get(id) {
+        const row = this.database.sqlite
+            .prepare("select * from tasks where id = ? limit 1")
+            .get(id);
+        return row ? rowToTask(row) : undefined;
+    }
+    list(scope = {}) {
+        let rows;
+        if (scope.workspaceId) {
+            rows = this.database.sqlite
+                .prepare("select * from tasks where workspace_id = ? order by updated_at desc")
+                .all(scope.workspaceId);
+        }
+        else if (scope.workspaceRoot) {
+            rows = this.database.sqlite
+                .prepare("select * from tasks where workspace_root = ? order by updated_at desc")
+                .all(resolve(scope.workspaceRoot));
+        }
+        else {
+            rows = this.database.sqlite
+                .prepare("select * from tasks order by updated_at desc limit 200")
+                .all();
+        }
+        return rows.map(rowToTask);
+    }
+    /**
+     * Applies a guarded transition, appending an evidence entry for the move.
+     * Returns the updated record; throws TaskTransitionError on illegal moves.
+     */
+    transition(id, to, options = {}) {
+        const current = this.get(id);
+        if (!current)
+            throw new Error(`Unknown task: ${id}`);
+        if (current.status === to)
+            return current;
+        if (!TRANSITIONS[current.status].includes(to)) {
+            throw new TaskTransitionError(current.status, to);
+        }
+        const evidence = [
+            ...current.evidence,
+            ...(options.evidence
+                ? [options.evidence]
+                : [{
+                        ts: new Date().toISOString(),
+                        kind: "note",
+                        summary: `status: ${current.status} → ${to}`,
+                    }]),
+        ];
+        this.database.sqlite
+            .prepare(`update tasks set
+          status = ?,
+          completion_state = ?,
+          plan = ?,
+          evidence = ?,
+          error = ?,
+          updated_at = ?
+         where id = ?`)
+            .run(to, options.completionState ?? (to === "completed" ? current.completionState ?? null : null), options.plan ? JSON.stringify(options.plan) : current.plan ? JSON.stringify(current.plan) : null, JSON.stringify(evidence), options.error ?? (to === "failed" || to === "cancelled" ? options.error ?? current.error ?? null : null), new Date().toISOString(), id);
+        return this.get(id);
+    }
+    /**
+     * Resume a failed task (e.g. after crash reconcile or repair-budget
+     * exhaustion) back to planning with an audit trail. Only failed tasks can
+     * resume; completed/cancelled are terminal and in-flight tasks use the
+     * normal transitions.
+     */
+    replan(id, reason = "Resumed by client.") {
+        const current = this.get(id);
+        if (!current)
+            throw new Error(`Unknown task: ${id}`);
+        if (current.status !== "failed") {
+            throw new TaskTransitionError(current.status, "planning");
+        }
+        const evidence = [
+            ...current.evidence,
+            { ts: new Date().toISOString(), kind: "note", summary: `resume: failed → planning (${reason})` },
+        ];
+        this.database.sqlite
+            .prepare("update tasks set status = 'planning', error = ?, evidence = ?, updated_at = ? where id = ?")
+            .run(null, JSON.stringify(evidence), new Date().toISOString(), id);
+        return this.get(id);
+    }
+    appendEvidence(id, entry) {
+        const current = this.get(id);
+        if (!current)
+            throw new Error(`Unknown task: ${id}`);
+        const evidence = [...current.evidence, entry];
+        this.database.sqlite
+            .prepare("update tasks set evidence = ?, updated_at = ? where id = ?")
+            .run(JSON.stringify(evidence), new Date().toISOString(), id);
+        return this.get(id);
+    }
+    countToolCall(id) {
+        this.database.sqlite
+            .prepare("update tasks set tool_calls = tool_calls + 1, updated_at = ? where id = ?")
+            .run(new Date().toISOString(), id);
+    }
+    /**
+     * Crash recovery: on boot, tasks that were mid-flight are not magically
+     * resumable (their driving client is gone), so they are failed with an
+     * explicit reason. Paused agents remain resumable; tasks are recreated or
+     * re-planned by the client.
+     */
+    reconcileOnBoot() {
+        const result = this.database.sqlite
+            .prepare(`update tasks
+         set status = 'failed',
+             error = 'Hearth restarted while the task was in flight.',
+             updated_at = ?
+         where status in ('executing', 'verifying', 'repairing')`)
+            .run(new Date().toISOString());
+        return Number(result.changes);
+    }
+    close() {
+        this.database.close();
+    }
+}
+function rowToTask(row) {
+    return {
+        id: row.id,
+        workspaceId: row.workspace_id ?? undefined,
+        workspaceRoot: row.workspace_root,
+        goal: row.goal,
+        status: readStatus(row.status),
+        completionState: readCompletionState(row.completion_state),
+        mode: readMode(row.mode),
+        plan: row.plan ? safeParseArray(row.plan) : undefined,
+        evidence: row.evidence ? safeParseArray(row.evidence) : [],
+        error: row.error ?? undefined,
+        toolCalls: Number(row.tool_calls ?? 0),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function readStatus(value) {
+    const allowed = ["planning", "executing", "verifying", "repairing", "completed", "failed", "cancelled"];
+    return allowed.includes(value) ? value : "failed";
+}
+function readCompletionState(value) {
+    return value === "verified_complete" || value === "model_complete" ? value : undefined;
+}
+function readMode(value) {
+    return value === "autonomous" || value === "readonly" ? value : "supervised";
+}
+function safeParseArray(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}