@sunshinelife83/hearth 1.0.0

package/dist/server.js

@@ -0,0 +1,980 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { checkResourceAllowed, resourceUrlFromServerUrl } from "@modelcontextprotocol/sdk/shared/auth-utils.js";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { toNodeHandler } from "@modelcontextprotocol/node";
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import express from "express";
+import * as z from "zod/v4";
+import { isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./artifact-tools.js";
+import { registerAgentTools } from "./agent-tools.js";
+import { registerDashboard, dashboardDirectory } from "./dashboard.js";
+import { loadMachineIdentity } from "./machine-id.js";
+import { expandHomePath } from "./roots.js";
+import { registerTaskTools } from "./task-tools.js";
+import { registerContextTools } from "./context/context-tools.js";
+import { TaskStore } from "./task-store.js";
+import { probeSandboxAdapter, wrapCommandWithSandbox } from "./policy/sandbox.js";
+import { resolveExecutionForWorkspace } from "./policy/workspace-profiles.js";
+import { loadConfig } from "./config.js";
+import { createOpenAIIncomingArtifactAdapter, } from "./incoming-artifacts.js";
+import { logEvent, requestIp, requestPath, } from "./logger.js";
+import { readFileTool } from "./pi-tools.js";
+import { RateLimiter, createAuthRateLimiters } from "./rate-limit.js";
+import { SingleUserOAuthProvider } from "./oauth-provider.js";
+import { compileMcpRegistrationSurface, createModernMcpServerAdapter, modernMcpAdapterErrorLogFields, } from "./mcp-modern-server.js";
+import { ProcessSessionManager } from "./process-sessions.js";
+import { createReviewCheckpointManager } from "./review-checkpoints.js";
+import { createSnapshot, listSnapshots, rollbackSnapshot, } from "./snapshot-manager.js";
+import { decideExecution } from "./policy/command-policy.js";
+import { conversationScopeIdFromRequestMeta } from "./request-meta.js";
+import { shutdownHttpServer } from "./server-shutdown.js";
+import { formatPathForPrompt } from "./skills.js";
+import { createWorkspaceStore } from "./workspace-store.js";
+import { formatAgentsPath, WorkspaceRegistry } from "./workspaces.js";
+import { getLocalAgentProviderAvailabilitySnapshot, } from "./local-agent-availability.js";
+import { buildLocalAgentCatalog, buildLocalAgentProviderStatuses, formatLocalAgentProviderStatusSummary, } from "./local-agent-catalog.js";
+import { getToolSurface } from "./tool-surfaces/index.js";
+import { contentText, logFailedToolResponse, logToolCall, resultOutputSchema, textBlock, workspaceAppDescriptorMeta, } from "./tool-surfaces/shared.js";
+import { WORKSPACE_APP_URI, toolNames, workspaceIdDescription, } from "./tool-surfaces/types.js";
+const WORKSPACE_APP_MANIFEST_ENTRY = "workspace-app.html";
+const SHUTDOWN_DRAIN_TIMEOUT_MS = 15_000;
+function mcpServerInfo() {
+    return {
+        name: "hearth",
+        title: "Hearth",
+        version: "0.1.0",
+        description: "Coding tools for project workspaces. Open each project or worktree once, then reuse its workspaceId.",
+    };
+}
+class ToolActivityTracker {
+    active = new Set();
+    track = (operation) => {
+        const promise = operation();
+        this.active.add(promise);
+        const remove = () => this.active.delete(promise);
+        void promise.then(remove, remove);
+        return promise;
+    };
+    activeCount() {
+        return this.active.size;
+    }
+    async waitForIdle(timeoutMs) {
+        if (timeoutMs === undefined) {
+            while (this.active.size > 0) {
+                await Promise.allSettled(Array.from(this.active));
+            }
+            return;
+        }
+        const deadline = new Promise((resolve) => {
+            const timer = setTimeout(resolve, timeoutMs);
+            timer.unref();
+        });
+        while (this.active.size > 0) {
+            await Promise.race([Promise.allSettled(Array.from(this.active)), deadline]);
+            if (this.active.size > 0)
+                break;
+        }
+    }
+}
+function serverInstructions(config, toolSurface) {
+    const artifactInstruction = config.artifactsEnabled && isArtifactDownloadSupportedPlatform()
+        ? " When the user supplies or generates a file that is not present on the Hearth host, use download_artifact with its native file value, the existing workspace ID, and a suitable relative destination path chosen from the user's request and project structure. The tool refuses to overwrite an existing destination and returns the normalized workspace-relative path. Use normal workspace tools when explicit inspection, replacement, movement, renaming, or deletion is needed. Do not recreate binary files with write/edit calls or place signed URLs, native file objects, base64 content, or invented host paths in shell commands or logs."
+        : "";
+    const showChangesInstruction = " If the turn successfully modifies files by creating, editing, overwriting, deleting, moving, or applying patches, call show_changes exactly once for that workspace after the final related file change and before your final response so the user can inspect the aggregate diff for that turn. Do not call it after every individual file change.";
+    const skills = config.skillsEnabled
+        ? `When ${toolNames.openWorkspace} returns available skills and a task matches a skill, use ${toolNames.read} to read that skill's path before proceeding. Skill paths may be outside the workspace, and ${toolNames.read} permits files within advertised skill directories. `
+        : "";
+    const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Before working under a path listed in availableAgentsFiles, use ${toolNames.read} to inspect that instruction file and follow it. `;
+    const common = `Use Hearth for coding work. Call ${toolNames.openWorkspace} once for each project folder or isolated worktree, then keep using its workspaceId. During continued work in the same project or worktree, do not call ${toolNames.openWorkspace} again. Open another workspace only when changing projects, switching checkout/worktree mode, creating another isolated worktree, or when the current workspaceId is rejected.`;
+    return `${common} ${toolSurface.instructions({ agents, skills })}${artifactInstruction}${showChangesInstruction}`;
+}
+function formatVisibleAgent(agent) {
+    const model = agent.model ? `, model ${agent.model}` : "";
+    const effort = agent.effort ? `, effort ${agent.effort}` : "";
+    return `${agent.name} (${agent.provider}${model}${effort})`;
+}
+function formatAvailableAgentProvider(provider) {
+    const details = [
+        provider.model ? `model ${provider.model}` : undefined,
+        provider.effort ? `effort ${provider.effort}` : undefined,
+        provider.note,
+    ].filter(Boolean).join(", ");
+    return `${provider.id}${details ? ` (${details})` : ""}`;
+}
+const workspaceSkillOutputSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    path: z.string(),
+});
+const workspaceAgentsFileOutputSchema = z.object({
+    path: z.string(),
+    content: z.string(),
+});
+const workspaceLocalAgentOutputSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    provider: z.string(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+});
+const workspaceLocalAgentProviderOutputSchema = z.object({
+    id: z.string(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+    note: z.string().optional(),
+});
+const workspaceAvailableAgentsFileOutputSchema = z.object({
+    path: z.string(),
+});
+function sendJsonRpcError(res, status, code, message) {
+    res.status(status).json({
+        jsonrpc: "2.0",
+        error: { code, message },
+        id: null,
+    });
+}
+function requestLogFields(req, config) {
+    return {
+        ip: requestIp(req, config.logging.trustProxy),
+        host: req.header("host"),
+        userAgent: req.header("user-agent"),
+        origin: req.header("origin"),
+        referer: req.header("referer"),
+        contentLength: req.header("content-length"),
+    };
+}
+function assetBaseUrl(config) {
+    return `${config.publicBaseUrl.replace(/\/+$/, "")}/mcp-app-assets`;
+}
+function uiManifestUrl() {
+    return new URL("../dist/ui/.vite/manifest.json", import.meta.url);
+}
+function readWorkspaceAppManifest() {
+    return JSON.parse(readFileSync(uiManifestUrl(), "utf8"));
+}
+function getWorkspaceAppManifestEntry() {
+    const manifest = readWorkspaceAppManifest();
+    const entry = manifest[WORKSPACE_APP_MANIFEST_ENTRY];
+    if (!entry?.file) {
+        throw new Error(`Missing ${WORKSPACE_APP_MANIFEST_ENTRY} in UI manifest.`);
+    }
+    return entry;
+}
+function assetUrl(baseUrl, assetPath) {
+    return `${baseUrl}/${assetPath.replace(/^\/+/, "")}`;
+}
+function workspaceAppHtml(config) {
+    const baseUrl = assetBaseUrl(config);
+    const entry = getWorkspaceAppManifestEntry();
+    const stylesheets = (entry.css ?? [])
+        .map((stylesheet) => `    <link rel="stylesheet" crossorigin href="${assetUrl(baseUrl, stylesheet)}" />`)
+        .join("\n");
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Hearth Workspace</title>
+    <script type="module" crossorigin src="${assetUrl(baseUrl, entry.file)}"></script>
+${stylesheets}
+  </head>
+  <body>
+    <main id="app" class="shell">
+      <section class="empty">Waiting for a tool result.</section>
+    </main>
+  </body>
+</html>`;
+}
+function appCsp(config) {
+    const publicBaseUrl = config.publicBaseUrl.replace(/\/+$/, "");
+    return {
+        resourceDomains: [publicBaseUrl],
+        connectDomains: [publicBaseUrl],
+    };
+}
+function uiBuildDirectory() {
+    return fileURLToPath(new URL("../dist/ui", import.meta.url));
+}
+function setAssetHeaders(res) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Range");
+    res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
+}
+async function assertWorkspaceAppAssets() {
+    const entry = getWorkspaceAppManifestEntry();
+    const candidates = [entry.file, ...(entry.css ?? [])].map((assetPath) => new URL(`../dist/ui/${assetPath}`, import.meta.url));
+    for (const candidate of candidates) {
+        await access(candidate);
+    }
+}
+export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, resolveLocalAgentProviders, incomingArtifactAdapters, trackToolActivity, taskStore) {
+    const toolSurface = getToolSurface(config.toolMode);
+    const server = new McpServer(mcpServerInfo(), {
+        instructions: serverInstructions(config, toolSurface),
+    });
+    registerMcpSurface(server, config, workspaces, reviewCheckpoints, processSessions, resolveLocalAgentProviders, incomingArtifactAdapters, trackToolActivity, taskStore);
+    return server;
+}
+function registerMcpSurface(server, config, workspaces, reviewCheckpoints, processSessions, resolveLocalAgentProviders, incomingArtifactAdapters, trackToolActivity, taskStore) {
+    const registrationTarget = trackToolActivity
+        ? withTrackedToolHandlers(server, trackToolActivity)
+        : server;
+    const toolSurface = getToolSurface(config.toolMode);
+    registerAppResource(registrationTarget, "Hearth Diff Card", WORKSPACE_APP_URI, {
+        description: "Interactive card for viewing Hearth file diffs.",
+        _meta: {
+            ui: {
+                csp: appCsp(config),
+            },
+        },
+    }, async () => {
+        await assertWorkspaceAppAssets();
+        return {
+            contents: [
+                {
+                    uri: WORKSPACE_APP_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: workspaceAppHtml(config),
+                    _meta: {
+                        ui: {
+                            csp: appCsp(config),
+                        },
+                    },
+                },
+            ],
+        };
+    });
+    registerAppTool(registrationTarget, "open_workspace", {
+        title: "Open workspace",
+        description: "Start work in a project directory or isolated worktree when no usable workspaceId exists for it. During continued work, reuse the existing workspaceId instead of calling this tool again. By default this uses the actual checkout; set mode=\"worktree\" for isolated or parallel work.",
+        inputSchema: {
+            path: z
+                .string()
+                .describe("Absolute path, or a leading-tilde home path such as ~/project, to a project directory inside an allowed root."),
+            mode: z
+                .enum(["checkout", "worktree"])
+                .optional()
+                .describe("Defaults to checkout, which works in the actual directory. Use worktree for isolated or parallel Git work."),
+            baseRef: z
+                .string()
+                .optional()
+                .describe("Git ref to base a worktree on. Only used with mode=\"worktree\". Defaults to HEAD."),
+        },
+        outputSchema: {
+            workspaceId: z.string(),
+            root: z.string(),
+            mode: z.enum(["checkout", "worktree"]),
+            sourceRoot: z.string().optional(),
+            worktree: z
+                .object({
+                path: z.string(),
+                baseRef: z.string(),
+                baseSha: z.string(),
+                dirtySource: z.boolean(),
+                detached: z.boolean(),
+                managed: z.boolean(),
+            })
+                .optional(),
+            agentsFiles: z.array(workspaceAgentsFileOutputSchema).optional(),
+            availableAgentsFiles: z.array(workspaceAvailableAgentsFileOutputSchema).optional(),
+            skills: z.array(workspaceSkillOutputSchema).optional(),
+            agentProviders: z.array(workspaceLocalAgentProviderOutputSchema).optional(),
+            agents: z.array(workspaceLocalAgentOutputSchema).optional(),
+            skillDiagnostics: z.array(z.unknown()).optional(),
+            review: z.discriminatedUnion("available", [
+                z.object({ available: z.literal(true) }),
+                z.object({
+                    available: z.literal(false),
+                    reason: z.string(),
+                }),
+            ]),
+            instruction: z.string(),
+        },
+        ...workspaceAppDescriptorMeta(config),
+        annotations: { readOnlyHint: true },
+    }, async ({ path, mode, baseRef }, { _meta }) => {
+        const startedAt = performance.now();
+        const { workspace, agentsFiles, availableAgentsFiles, workspaceReused, includeBootstrapContext, } = await workspaces.openWorkspace({ path, mode, baseRef }, { conversationScopeId: conversationScopeIdFromRequestMeta(_meta) });
+        const review = await reviewCheckpoints.initializeWorkspace({
+            workspaceId: workspace.id,
+            root: workspace.root,
+        });
+        const cardSkills = workspace.skills
+            .filter((skill) => !skill.disableModelInvocation)
+            .map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+            path: formatPathForPrompt(skill.filePath),
+        }));
+        const agentCatalog = buildLocalAgentCatalog(config.subagents, workspace.agentProfiles, resolveLocalAgentProviders());
+        const cardAgentProviders = agentCatalog.providers
+            .filter((provider) => provider.usable)
+            .map((provider) => ({
+            id: provider.id,
+            model: provider.model,
+            effort: provider.effort,
+            note: provider.note,
+        }));
+        const cardAgents = agentCatalog.profiles;
+        const cardAgentsFiles = agentsFiles.map((file) => ({
+            path: formatAgentsPath(file.path, workspace.root),
+            content: file.content,
+        }));
+        const cardAvailableAgentsFiles = availableAgentsFiles.map((file) => ({
+            path: formatAgentsPath(file.path, workspace.root),
+        }));
+        const visibleSkills = includeBootstrapContext ? cardSkills : [];
+        const visibleAgentProviders = includeBootstrapContext ? cardAgentProviders : [];
+        const visibleAgents = includeBootstrapContext ? cardAgents : [];
+        const loadedAgentsFiles = includeBootstrapContext ? cardAgentsFiles : [];
+        const availableAgentsFileOutputs = includeBootstrapContext ? cardAvailableAgentsFiles : [];
+        const cardInstruction = config.skillsEnabled
+            ? "Use this workspaceId for subsequent work in this project. Keep reusing it while working in this project. Follow loaded agentsFiles instructions. Before working under a path listed in availableAgentsFiles, read that instruction file. When a task matches an available skill in skills, read its path before proceeding."
+            : "Use this workspaceId for subsequent work in this project. Keep reusing it while working in this project. Follow loaded agentsFiles instructions. Before working under a path listed in availableAgentsFiles, read that instruction file.";
+        const instruction = workspaceReused
+            ? [
+                `Workspace already open as ${workspace.id}.`,
+                "Continue with this workspaceId.",
+                "Keep following the project instructions, nested instruction files, skills, agent profiles, and diagnostics already provided for this workspace.",
+            ].join("\n\n")
+            : workspace.mode === "worktree"
+                ? "Use this workspaceId for subsequent work in this isolated worktree. Keep reusing it while working in this worktree. Follow the project instructions, nested instruction files, skills, agent profiles, and diagnostics returned for it."
+                : cardInstruction;
+        const resultContent = [
+            {
+                type: "text",
+                text: [
+                    workspaceReused
+                        ? `Workspace already open as ${workspace.id}.`
+                        : workspace.mode === "worktree"
+                            ? `Opened isolated worktree workspace ${workspace.id}.`
+                            : `Opened workspace ${workspace.id}.`,
+                    `Root: ${workspace.root}`,
+                    `Mode: ${workspace.mode}`,
+                    loadedAgentsFiles.length > 0
+                        ? `Loaded project instructions: ${loadedAgentsFiles.map((file) => file.path).join(", ")}`
+                        : undefined,
+                    availableAgentsFileOutputs.length > 0
+                        ? `Available nested instructions: ${availableAgentsFileOutputs.map((file) => file.path).join(", ")}`
+                        : undefined,
+                    visibleSkills.length > 0
+                        ? `Available skills: ${visibleSkills.map((skill) => skill.name).join(", ")}`
+                        : undefined,
+                    visibleAgentProviders.length > 0
+                        ? `Available subagent providers: ${visibleAgentProviders.map(formatAvailableAgentProvider).join(", ")}`
+                        : undefined,
+                    visibleAgents.length > 0
+                        ? `Available subagent profiles: ${visibleAgents.map(formatVisibleAgent).join(", ")}`
+                        : undefined,
+                    instruction,
+                ].filter(Boolean).join("\n"),
+            },
+        ];
+        logToolCall(config, {
+            tool: "open_workspace",
+            workspaceId: workspace.id,
+            path: workspace.root,
+            success: true,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return {
+            content: resultContent,
+            _meta: {
+                card: {
+                    workspaceId: workspace.id,
+                    root: workspace.root,
+                    path: workspace.root,
+                    mode: workspace.mode,
+                    workspaceReused,
+                    includeBootstrapContext,
+                    sourceRoot: workspace.sourceRoot,
+                    worktree: workspace.worktree,
+                    agentsFiles: cardAgentsFiles,
+                    availableAgentsFiles: cardAvailableAgentsFiles,
+                    skills: cardSkills,
+                    agentProviders: cardAgentProviders,
+                    agents: cardAgents,
+                    review,
+                    instruction: cardInstruction,
+                    summary: {
+                        mode: workspace.mode,
+                        agentsFiles: cardAgentsFiles.length,
+                        availableAgentsFiles: cardAvailableAgentsFiles.length,
+                        skills: cardSkills.length,
+                        agentProviders: cardAgentProviders.length,
+                        agents: cardAgents.length,
+                    },
+                },
+            },
+            structuredContent: {
+                workspaceId: workspace.id,
+                root: workspace.root,
+                mode: workspace.mode,
+                sourceRoot: workspace.sourceRoot,
+                worktree: workspace.worktree,
+                review,
+                ...(includeBootstrapContext
+                    ? {
+                        agentsFiles: loadedAgentsFiles,
+                        availableAgentsFiles: availableAgentsFileOutputs,
+                        skills: visibleSkills,
+                        agentProviders: visibleAgentProviders,
+                        agents: visibleAgents,
+                        skillDiagnostics: workspace.skillDiagnostics,
+                    }
+                    : {}),
+                instruction,
+            },
+        };
+    });
+    registrationTarget.registerTool(toolNames.read, {
+        title: "Read file",
+        description: [
+            "Read a file in a workspace. Use this for file inspection instead of shell commands like cat or sed.",
+            "Use this tool to inspect relevant AGENTS.md or CLAUDE.md files listed by open_workspace before working in nested directories.",
+            config.skillsEnabled
+                ? "If available skills were returned and a task matches one, read that skill's path before proceeding. Skill paths may be outside the workspace; files within advertised skill directories are readable."
+                : "",
+        ]
+            .filter(Boolean)
+            .join(" "),
+        inputSchema: {
+            workspaceId: z
+                .string()
+                .describe(workspaceIdDescription),
+            path: z
+                .string()
+                .describe(config.skillsEnabled
+                ? "File path to read, relative to the workspace root. May also be an advertised skill path from open_workspace skills."
+                : "File path to read, relative to the workspace root."),
+            offset: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("1-indexed line number to start reading from."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Maximum number of lines to read."),
+        },
+        outputSchema: resultOutputSchema(),
+        annotations: { readOnlyHint: true },
+    }, async ({ workspaceId, ...input }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        const readPath = workspaces.resolveReadPath(workspace, input.path);
+        const response = await readFileTool({ ...input, path: readPath.absolutePath }, {
+            cwd: workspace.root,
+            root: workspace.root,
+            readRoots: readPath.readRoots,
+        });
+        if (response.isError) {
+            logFailedToolResponse(config, {
+                tool: toolNames.read,
+                workspaceId,
+                path: input.path,
+            }, response.content, startedAt);
+            return response;
+        }
+        logToolCall(config, {
+            tool: toolNames.read,
+            workspaceId,
+            path: input.path,
+            success: true,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return {
+            ...response,
+            structuredContent: {
+                result: contentText(response.content),
+            },
+        };
+    });
+    toolSurface.register({
+        server: registrationTarget,
+        config,
+        workspaces,
+        processSessions,
+    });
+    registerAppTool(registrationTarget, "show_changes", {
+        title: "Show changes",
+        description: "Show the changes made in this turn for an open workspace. Call this once after the final related file change and before your final response so the user can review the combined diff. Do not call it after each individual file change.",
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+        },
+        outputSchema: resultOutputSchema({
+            workspaceId: z.string(),
+            reviewRef: z.string().regex(/^[0-9a-f]{40,64}$/),
+        }),
+        ...workspaceAppDescriptorMeta(config),
+        annotations: { readOnlyHint: true },
+    }, async ({ workspaceId }, { _meta }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        const reviewRef = typeof _meta?.["hearth/reviewRef"] === "string"
+            ? _meta["hearth/reviewRef"]
+            : undefined;
+        const review = reviewRef
+            ? await reviewCheckpoints.reviewByRef({
+                workspaceId,
+                root: workspace.root,
+                reviewRef,
+            })
+            : await reviewCheckpoints.reviewChanges({
+                workspaceId,
+                root: workspace.root,
+                markReviewed: true,
+            });
+        const content = [textBlock(review.result)];
+        logToolCall(config, {
+            tool: "show_changes",
+            workspaceId,
+            success: true,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return {
+            content,
+            _meta: {
+                card: {
+                    workspaceId,
+                    summary: review.summary,
+                    files: review.files,
+                    payload: {
+                        patch: review.patch,
+                    },
+                },
+            },
+            structuredContent: {
+                workspaceId,
+                reviewRef: review.reviewRef,
+                result: contentText(content),
+            },
+        };
+    });
+    registerAgentTools(registrationTarget, { config, workspaces, taskStore });
+    registerContextTools(registrationTarget, { config, workspaces });
+    if (taskStore) {
+        registerTaskTools(registrationTarget, { config, workspaces, processSessions, taskStore });
+    }
+    if (config.artifactsEnabled && isArtifactDownloadSupportedPlatform()) {
+        registerArtifactTools(registrationTarget, {
+            config,
+            workspaces,
+            incomingArtifactAdapters,
+        });
+    }
+    registrationTarget.registerTool("create_snapshot", {
+        title: "Create snapshot",
+        description: "Capture a restorable snapshot of the workspace working tree (tracked and untracked files, not git-ignored ones) as a git ref. Use before risky multi-step changes so the work can be restored later.",
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+            label: z
+                .string()
+                .trim()
+                .min(1)
+                .max(120)
+                .optional()
+                .describe("Short label describing the upcoming change."),
+        },
+        outputSchema: resultOutputSchema({
+            snapshotId: z.string(),
+            label: z.string(),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ workspaceId, label }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        try {
+            const snapshot = await createSnapshot({
+                root: workspace.root,
+                workspaceId,
+                label: label ?? "manual",
+            });
+            const result = `Snapshot created: ${snapshot.snapshotId}`;
+            logToolCall(config, {
+                tool: "create_snapshot",
+                workspaceId,
+                success: true,
+                durationMs: Math.round(performance.now() - startedAt),
+            });
+            return {
+                content: [textBlock(result)],
+                structuredContent: { result, snapshotId: snapshot.snapshotId, label: snapshot.label },
+            };
+        }
+        catch (error) {
+            logFailedToolResponse(config, {
+                tool: "create_snapshot",
+                workspaceId,
+            }, [textBlock(error instanceof Error ? error.message : String(error))], startedAt);
+            throw error;
+        }
+    });
+    registrationTarget.registerTool("list_snapshots", {
+        title: "List snapshots",
+        description: "List restorable snapshots previously captured for this workspace.",
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+        },
+        outputSchema: resultOutputSchema(),
+        annotations: { readOnlyHint: true },
+    }, async ({ workspaceId }) => {
+        const workspace = workspaces.getWorkspace(workspaceId);
+        const records = await listSnapshots({ root: workspace.root, workspaceId });
+        const lines = records.length > 0
+            ? records.map((record) => `${record.snapshotId}  ${record.createdAt}  ${record.label}`).join("\n")
+            : "No snapshots for this workspace yet.";
+        return {
+            content: [textBlock(lines)],
+            structuredContent: {
+                result: lines,
+                snapshots: records.map((record) => ({
+                    snapshotId: record.snapshotId,
+                    label: record.label,
+                    createdAt: record.createdAt,
+                })),
+            },
+        };
+    });
+    registrationTarget.registerTool("rollback_snapshot", {
+        title: "Rollback to snapshot",
+        description: "Restore the workspace working tree to a previously captured snapshot. Files changed since the snapshot are reverted (including deletions and creations); git-ignored files and the repository HEAD are untouched. Tier-2 policy applies like shell commands.",
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+            snapshotId: z
+                .string()
+                .regex(/^[0-9a-f]{40,64}$/)
+                .describe("Snapshot ID returned by create_snapshot or list_snapshots."),
+            approvedByUser: z
+                .boolean()
+                .optional()
+                .describe("Set to true only after the user explicitly approved this rollback in the conversation. Required in supervised mode."),
+        },
+        outputSchema: resultOutputSchema(),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    }, async ({ workspaceId, snapshotId, approvedByUser }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        const decision = decideExecution({
+            mode: config.execution.mode,
+            tier: 2,
+            approvedByUser,
+        });
+        logEvent(config.logging, decision.decision === "allow" ? "info" : "warn", "policy_decision", {
+            tool: "rollback_snapshot",
+            workspaceId,
+            tier: 2,
+            decision: decision.decision,
+            mode: config.execution.mode,
+            approvalClaimed: decision.approvalClaimed ?? false,
+        });
+        if (decision.decision !== "allow") {
+            return {
+                content: [textBlock(decision.reason)],
+                isError: true,
+                structuredContent: { result: decision.reason, policy: { decision: decision.decision, tier: 2 } },
+            };
+        }
+        const rollback = await rollbackSnapshot({
+            root: workspace.root,
+            workspaceId,
+            snapshotId,
+        });
+        const result = rollback.files > 0
+            ? `Rolled back ${rollback.files} file(s) to snapshot ${snapshotId}.`
+            : `Workspace already matches snapshot ${snapshotId}.`;
+        logToolCall(config, {
+            tool: "rollback_snapshot",
+            workspaceId,
+            success: true,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return {
+            content: [textBlock(result)],
+            structuredContent: { result, files: rollback.files },
+        };
+    });
+}
+function withTrackedToolHandlers(server, trackToolActivity) {
+    return {
+        registerTool: ((...args) => {
+            const handler = args.at(-1);
+            return server.registerTool(...args.slice(0, -1), (...handlerArgs) => trackToolActivity(() => Promise.resolve(handler(...handlerArgs))));
+        }),
+        registerResource: server.registerResource.bind(server),
+    };
+}
+export function createServer(config = loadConfig(), options = {}) {
+    const incomingArtifactAdapters = options.incomingArtifactAdapters
+        ?? [createOpenAIIncomingArtifactAdapter()];
+    const allowedHosts = config.allowedHosts.includes("*")
+        ? undefined
+        : Array.from(new Set([config.host, ...config.allowedHosts]));
+    const app = createMcpExpressApp({
+        host: config.host,
+        ...(allowedHosts ? { allowedHosts } : {}),
+    });
+    const mcpUrl = new URL("/mcp", config.publicBaseUrl);
+    const resourceServerUrl = resourceUrlFromServerUrl(mcpUrl);
+    const rateLimiters = createAuthRateLimiters(config.oauth.trustProxy);
+    const ownerTokenFailureLimiter = new RateLimiter({
+        keyPrefix: "owner-token-failure",
+        rule: { limit: 8, windowMs: 60 * 60 * 1000 },
+    });
+    const oauthProvider = new SingleUserOAuthProvider(config.oauth, mcpUrl, config.stateDir, ownerTokenFailureLimiter);
+    const bearerAuth = requireBearerAuth({
+        verifier: oauthProvider,
+        requiredScopes: [config.oauth.scopes[0] ?? "hearth"],
+        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(resourceServerUrl),
+    });
+    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)).then((report) => {
+        if (report.reaped > 0 || report.errors.length > 0) {
+            logEvent(config.logging, "warn", "orphan_reap_boot", {
+                reaped: report.reaped,
+                skipped: report.skipped,
+                errors: report.errors.slice(0, 5),
+            });
+        }
+    }).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 toolActivities = new ToolActivityTracker();
+    const localAgentProviders = buildLocalAgentProviderStatuses(config.subagents, getLocalAgentProviderAvailabilitySnapshot());
+    const resolveLocalAgentProviders = () => buildLocalAgentProviderStatuses(config.subagents, getLocalAgentProviderAvailabilitySnapshot());
+    const modernToolSurface = getToolSurface(config.toolMode);
+    const bindModernMcpSurface = compileMcpRegistrationSurface((target) => {
+        registerMcpSurface(target, config, workspaces, reviewCheckpoints, processSessions, resolveLocalAgentProviders, incomingArtifactAdapters, toolActivities.track, taskStore);
+    });
+    const logMcpHandlerError = (error) => logEvent(config.logging, "error", "mcp_handler_error", modernMcpAdapterErrorLogFields(error));
+    const mcpHandler = createMcpHandler(() => {
+        const adapter = createModernMcpServerAdapter(mcpServerInfo(), { instructions: serverInstructions(config, modernToolSurface) });
+        bindModernMcpSurface(adapter.registrationTarget);
+        return adapter.server;
+    }, {
+        legacy: "stateless",
+        onerror: logMcpHandlerError,
+    });
+    const mcpNodeHandler = toNodeHandler(mcpHandler, {
+        onerror: logMcpHandlerError,
+    });
+    if (config.logging.trustProxy) {
+        app.set("trust proxy", true);
+    }
+    app.use((req, res, next) => {
+        const requestId = randomUUID();
+        const startedAt = performance.now();
+        res.locals.requestId = requestId;
+        res.on("finish", () => {
+            const path = requestPath(req);
+            if (!config.logging.requests)
+                return;
+            if (!config.logging.assets && path.startsWith("/mcp-app-assets"))
+                return;
+            logEvent(config.logging, "info", "http_request", {
+                requestId,
+                method: req.method,
+                path,
+                status: res.statusCode,
+                durationMs: Math.round(performance.now() - startedAt),
+                ...requestLogFields(req, config),
+            });
+        });
+        next();
+    });
+    app.use("/authorize", rateLimiters.authorizeIpMiddleware);
+    app.use("/register", rateLimiters.registerIpMiddleware);
+    app.use("/token", rateLimiters.tokenIpMiddleware);
+    app.use(mcpAuthRouter({
+        provider: oauthProvider,
+        issuerUrl: new URL(config.oauthIssuerUrl),
+        baseUrl: new URL(config.oauthIssuerUrl),
+        resourceServerUrl,
+        scopesSupported: config.oauth.scopes,
+        resourceName: "Hearth",
+    }));
+    app.options("/mcp-app-assets/{*asset}", (_req, res) => {
+        setAssetHeaders(res);
+        res.sendStatus(204);
+    });
+    app.use("/mcp-app-assets", express.static(uiBuildDirectory(), {
+        immutable: true,
+        maxAge: "1y",
+        fallthrough: false,
+        setHeaders: setAssetHeaders,
+    }));
+    app.get("/healthz", (_req, res) => {
+        let machineId;
+        try {
+            machineId = loadMachineIdentity(config.stateDir).id;
+        }
+        catch {
+            machineId = undefined;
+        }
+        res.json({
+            ok: true,
+            name: "hearth",
+            ...(machineId ? { machineId } : {}),
+            mcp: new URL("/mcp", config.publicBaseUrl).toString(),
+        });
+    });
+    // ACME HTTP-01 challenge passthrough for relay-free TLS: serve only
+    // /.well-known/acme-challenge/* from the configured directory so certbot
+    // webroot mode works while the server runs. Nothing else is exposed here.
+    if (config.tls.acmeDir) {
+        const acmeDir = expandHomePath(config.tls.acmeDir);
+        app.use("/.well-known/acme-challenge", express.static(acmeDir, { fallthrough: false, maxAge: 0 }));
+    }
+    app.get("/", (_req, res) => {
+        res.sendFile("landing.html", { root: dashboardDirectory() });
+    });
+    registerDashboard(app, {
+        config,
+        workspaces,
+        taskStore,
+        resolveLocalAgentProviders,
+    });
+    app.all("/mcp", async (req, res) => {
+        const requestId = res.locals.requestId;
+        await new Promise((resolve, reject) => {
+            bearerAuth(req, res, (error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+        if (res.headersSent)
+            return;
+        if (!req.auth?.resource || !checkResourceAllowed({ requestedResource: req.auth.resource, configuredResource: resourceServerUrl })) {
+            logEvent(config.logging, "warn", "auth_denied", {
+                requestId,
+                method: req.method,
+                path: requestPath(req),
+                reason: "invalid_oauth_resource",
+                ...requestLogFields(req, config),
+            });
+            sendJsonRpcError(res, 401, -32001, "Unauthorized");
+            return;
+        }
+        logEvent(config.logging, "debug", "mcp_request", {
+            requestId,
+            method: req.method,
+        });
+        try {
+            await mcpNodeHandler(req, res, req.body);
+        }
+        catch (error) {
+            logEvent(config.logging, "error", "mcp_request_error", {
+                requestId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (!res.headersSent) {
+                sendJsonRpcError(res, 500, -32603, "Internal server error");
+            }
+        }
+    });
+    let closePromise;
+    return {
+        app,
+        config,
+        localAgentProviders,
+        close: () => {
+            closePromise ??= (async () => {
+                try {
+                    await mcpHandler.close();
+                }
+                catch (error) {
+                    logEvent(config.logging, "warn", "mcp_handler_close_failed", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                await toolActivities.waitForIdle(SHUTDOWN_DRAIN_TIMEOUT_MS);
+                if (toolActivities.activeCount() > 0) {
+                    logEvent(config.logging, "warn", "shutdown_drain_timeout", {
+                        activeToolCalls: toolActivities.activeCount(),
+                    });
+                }
+                processSessions.shutdown();
+                oauthProvider.close();
+                workspaceStore.close?.();
+                taskStore.close();
+            })();
+            return closePromise;
+        },
+    };
+}
+async function isMainModule() {
+    if (!process.argv[1])
+        return false;
+    const modulePath = await realpath(fileURLToPath(import.meta.url));
+    const entrypointPath = await realpath(process.argv[1]);
+    return modulePath === entrypointPath;
+}
+if (await isMainModule()) {
+    const { app, config, close, localAgentProviders } = createServer();
+    const httpServer = app.listen(config.port, config.host, () => {
+        console.log(`hearth listening on http://${config.host}:${config.port}/mcp`);
+        console.log(`allowed roots: ${config.allowedRoots.join(", ")}`);
+        console.log("auth: oauth owner-token flow required");
+        console.log(`logging: ${config.logging.level} ${config.logging.format}`);
+        console.log(`request logging: ${config.logging.requests ? "enabled" : "disabled"}`);
+        console.log(`asset logging: ${config.logging.assets ? "enabled" : "disabled"}`);
+        console.log(`trust proxy: ${config.logging.trustProxy ? "enabled" : "disabled"}`);
+        const artifactDownloadStatus = !config.artifactsEnabled
+            ? "disabled"
+            : isArtifactDownloadSupportedPlatform()
+                ? "enabled"
+                : `unsupported on ${process.platform}`;
+        console.log(`native artifact download: ${artifactDownloadStatus}`);
+        console.log(`subagent providers: ${formatLocalAgentProviderStatusSummary(localAgentProviders)}`);
+    });
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        await shutdownHttpServer(httpServer, close);
+        process.exit(0);
+    };
+    const handleShutdown = () => {
+        void shutdown().catch((error) => {
+            console.error("hearth shutdown failed", error);
+            process.exit(1);
+        });
+    };
+    process.once("SIGINT", handleShutdown);
+    process.once("SIGTERM", handleShutdown);
+}