@sunshinelife83/hearth 1.0.0

package/dist/process-sessions.js

@@ -0,0 +1,388 @@
+import { spawn } from "node:child_process";
+import { filterChildEnvironment } from "./policy/env-allowlist.js";
+import { resolveShellCommand, terminateProcessTree } from "./process-platform.js";
+const DEFAULT_EXEC_YIELD_MS = 10_000;
+const DEFAULT_INTERACTIVE_YIELD_MS = 250;
+const DEFAULT_POLL_YIELD_MS = 5_000;
+const MAX_COMMAND_YIELD_MS = 30_000;
+const MAX_POLL_YIELD_MS = 110_000;
+const DEFAULT_MAX_OUTPUT_TOKENS = 10_000;
+const DEFAULT_BUFFER_CHARACTERS = 1_000_000;
+const COMPLETED_SESSION_TTL_MS = 5 * 60 * 1_000;
+const DEFAULT_COLUMNS = 80;
+const DEFAULT_ROWS = 24;
+function boundedInteger(value, fallback, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error("Duration and output limits must be non-negative.");
+    }
+    return Math.min(Math.floor(value), maximum);
+}
+function terminalSize(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1 || value > 1_000) {
+        throw new Error("Terminal dimensions must be integers between 1 and 1000.");
+    }
+    return value;
+}
+function processEnvironment(baseEnvironment, input) {
+    return {
+        ...baseEnvironment,
+        NO_COLOR: "1",
+        TERM: "dumb",
+        PAGER: "cat",
+        GIT_PAGER: "cat",
+        GH_PAGER: "cat",
+        CODEX_CI: "1",
+        LANG: process.env.LANG ?? "C.UTF-8",
+        LC_ALL: process.env.LC_ALL ?? "C.UTF-8",
+        // Marks shells spawned by Hearth tools so CLI helpers invoked from a
+        // model-run command cannot bypass workspace scoping.
+        HEARTH_ORIGIN: "hearth-shell",
+        ...(input?.workspaceId ? { HEARTH_WORKSPACE_ID: input.workspaceId } : {}),
+        ...(input?.workspaceRoot ? { HEARTH_WORKSPACE_ROOT: input.workspaceRoot } : {}),
+    };
+}
+function codePointLength(value) {
+    return Array.from(value).length;
+}
+function sliceCodePoints(value, start, end) {
+    return Array.from(value).slice(start, end).join("");
+}
+function takeHead(value, count) {
+    if (count <= 0)
+        return "";
+    return sliceCodePoints(value, 0, count);
+}
+function takeTail(value, count) {
+    if (count <= 0)
+        return "";
+    const characters = Array.from(value);
+    return characters.slice(Math.max(0, characters.length - count)).join("");
+}
+function splitBudget(maxCharacters) {
+    return {
+        head: Math.ceil(maxCharacters / 2),
+        tail: Math.floor(maxCharacters / 2),
+    };
+}
+function formatHeadTail(head, tail, omittedCharacters) {
+    if (omittedCharacters <= 0)
+        return head + tail;
+    return `${head}\n... output truncated (${omittedCharacters} characters omitted) ...\n${tail}`;
+}
+export class HeadTailBuffer {
+    maxCharacters;
+    head = "";
+    tail = "";
+    totalCharacters = 0;
+    constructor(maxCharacters) {
+        this.maxCharacters = maxCharacters;
+        if (!Number.isInteger(maxCharacters) || maxCharacters < 1) {
+            throw new Error("Head/tail buffer limit must be a positive integer.");
+        }
+    }
+    append(output) {
+        if (!output)
+            return;
+        const previousTotal = this.totalCharacters;
+        this.totalCharacters += codePointLength(output);
+        if (this.totalCharacters <= this.maxCharacters) {
+            this.head += output;
+            return;
+        }
+        const budget = splitBudget(this.maxCharacters);
+        if (previousTotal <= this.maxCharacters) {
+            const fullOutput = this.head + output;
+            this.head = takeHead(fullOutput, budget.head);
+            this.tail = takeTail(fullOutput, budget.tail);
+            return;
+        }
+        this.tail = takeTail(this.tail + output, budget.tail);
+    }
+    hasOutput() {
+        return this.totalCharacters > 0;
+    }
+    drain(maxCharacters) {
+        if (!Number.isInteger(maxCharacters) || maxCharacters < 1) {
+            throw new Error("Output limit must be a positive integer.");
+        }
+        const omittedByBuffer = Math.max(0, this.totalCharacters - codePointLength(this.head) - codePointLength(this.tail));
+        const retained = formatHeadTail(this.head, this.tail, omittedByBuffer);
+        const output = truncateOutput(retained, maxCharacters);
+        const truncated = omittedByBuffer > 0 || output.truncated;
+        this.head = "";
+        this.tail = "";
+        this.totalCharacters = 0;
+        return { output: output.output, truncated };
+    }
+}
+function truncateOutput(output, maxCharacters) {
+    const outputCharacters = codePointLength(output);
+    if (outputCharacters <= maxCharacters)
+        return { output, truncated: false };
+    const marker = "\n... output truncated ...\n";
+    const markerCharacters = codePointLength(marker);
+    const available = Math.max(0, maxCharacters - markerCharacters);
+    const budget = splitBudget(available);
+    return {
+        output: takeHead(output, budget.head) + marker + takeTail(output, budget.tail),
+        truncated: true,
+    };
+}
+export class ProcessSessionManager {
+    sessions = new Map();
+    maxBufferCharacters;
+    completedSessionTtlMs;
+    environment;
+    commandWrapper;
+    journalDir;
+    nextSessionId = 1;
+    constructor(options = {}) {
+        this.maxBufferCharacters = options.maxBufferCharacters ?? DEFAULT_BUFFER_CHARACTERS;
+        this.completedSessionTtlMs = options.completedSessionTtlMs ?? COMPLETED_SESSION_TTL_MS;
+        this.environment = options.environment ?? { allowAll: true };
+        this.commandWrapper = options.commandWrapper;
+        this.journalDir = options.journalDir;
+    }
+    async start(input) {
+        const session = this.createSession(input);
+        this.sessions.set(session.id, session);
+        try {
+            if (input.tty && process.platform !== "win32")
+                await this.startPty(session, input);
+            else
+                this.startPipe(session, input);
+        }
+        catch (error) {
+            this.sessions.delete(session.id);
+            throw error;
+        }
+        const yieldTimeMs = boundedInteger(input.yieldTimeMs, DEFAULT_EXEC_YIELD_MS, MAX_COMMAND_YIELD_MS);
+        await this.waitForExit(session, yieldTimeMs);
+        const snapshot = this.consume(session, input.maxOutputTokens);
+        if (!session.running)
+            this.removeSession(session.id);
+        return snapshot;
+    }
+    async write(input) {
+        const session = this.getOwnedSession(input.workspaceId, input.sessionId);
+        const chars = input.chars ?? "";
+        const interactionRequested = chars.length > 0 || input.columns !== undefined || input.rows !== undefined;
+        if (input.columns !== undefined || input.rows !== undefined) {
+            session.columns = terminalSize(input.columns, session.columns);
+            session.rows = terminalSize(input.rows, session.rows);
+            if (!session.process?.resize) {
+                throw new Error(`Process session ${session.id} is not a PTY and cannot be resized.`);
+            }
+            session.process.resize(session.columns, session.rows);
+        }
+        const interruptRequested = chars.includes("\u0003") && session.running;
+        if (interruptRequested) {
+            session.process?.kill("SIGINT");
+        }
+        const writableChars = chars.replaceAll("\u0003", "");
+        if (writableChars && session.running)
+            session.process?.write(writableChars);
+        if ((interactionRequested || !session.buffer.hasOutput()) && session.running) {
+            const fallback = interactionRequested ? DEFAULT_INTERACTIVE_YIELD_MS : DEFAULT_POLL_YIELD_MS;
+            const maximum = interactionRequested ? MAX_COMMAND_YIELD_MS : MAX_POLL_YIELD_MS;
+            const yieldTimeMs = boundedInteger(input.yieldTimeMs, fallback, maximum);
+            await this.waitForExit(session, yieldTimeMs);
+        }
+        const snapshot = this.consume(session, input.maxOutputTokens);
+        if (!session.running)
+            this.removeSession(session.id);
+        return snapshot;
+    }
+    terminate(workspaceId, sessionId) {
+        const session = this.getOwnedSession(workspaceId, sessionId);
+        if (session.running)
+            session.process?.kill("SIGTERM");
+    }
+    shutdown() {
+        for (const session of this.sessions.values()) {
+            if (session.cleanupTimer)
+                clearTimeout(session.cleanupTimer);
+            if (session.running)
+                session.process?.kill("SIGTERM");
+        }
+        this.sessions.clear();
+    }
+    async waitForExit(session, yieldTimeMs) {
+        let timer;
+        try {
+            await Promise.race([
+                session.exitPromise,
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, yieldTimeMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    resolveShell(input) {
+        const shell = resolveShellCommand(input.command);
+        if (input.sandbox && this.commandWrapper && input.workspaceRoot) {
+            try {
+                return this.commandWrapper(shell, { workspaceRoot: input.workspaceRoot });
+            }
+            catch {
+                // Sandbox failures fall back to the unwrapped command; the wrapper
+                // logs why (best-effort hardening, never a silent behavior change).
+            }
+        }
+        return shell;
+    }
+    createSession(input) {
+        let resolveExit = () => undefined;
+        const exitPromise = new Promise((resolve) => {
+            resolveExit = resolve;
+        });
+        return {
+            id: this.nextSessionId++,
+            workspaceId: input.workspaceId,
+            startedAt: Date.now(),
+            columns: terminalSize(input.columns, DEFAULT_COLUMNS),
+            rows: terminalSize(input.rows, DEFAULT_ROWS),
+            buffer: new HeadTailBuffer(this.maxBufferCharacters),
+            running: true,
+            exitPromise,
+            resolveExit,
+        };
+    }
+    startPipe(session, input) {
+        const shell = this.resolveShell(input);
+        const detached = process.platform !== "win32";
+        // Spawn the resolved (possibly sandbox-wrapped) shell directly. Node's
+        // `shell:` spawn option would append `-c <command>` to whatever executable
+        // it is given, which breaks wrappers like `bwrap` ("Unknown option -c").
+        // resolveShellCommand already embeds the command in shell.args.
+        const child = spawn(shell.executable, shell.args, {
+            cwd: input.cwd,
+            env: processEnvironment(filterChildEnvironment(process.env, this.environment, { workspaceId: input.workspaceId }), {
+                workspaceId: input.workspaceId,
+                workspaceRoot: input.workspaceRoot,
+            }),
+            stdio: "pipe",
+            windowsHide: true,
+            detached,
+        });
+        session.process = {
+            write: (data) => child.stdin.write(data),
+            kill: (signal = "SIGTERM") => terminateProcessTree(child, signal, detached),
+            resize: input.tty ? () => undefined : undefined,
+        };
+        child.stdout.on("data", (data) => this.append(session, data.toString("utf8")));
+        child.stderr.on("data", (data) => this.append(session, data.toString("utf8")));
+        child.on("error", (error) => this.append(session, `${error.message}\n`));
+        child.on("close", (code, signal) => this.finish(session, code ?? undefined, signal ?? undefined));
+        this.journal(session, input, child.pid);
+    }
+    async startPty(session, input) {
+        let nodePty;
+        try {
+            nodePty = await import("node-pty");
+        }
+        catch {
+            throw new Error("PTY support requires the optional node-pty dependency.");
+        }
+        const shell = this.resolveShell(input);
+        let pty;
+        try {
+            pty = nodePty.spawn(shell.executable, shell.args, {
+                cwd: input.cwd,
+                env: processEnvironment(filterChildEnvironment(process.env, this.environment, { workspaceId: input.workspaceId }), {
+                    workspaceId: input.workspaceId,
+                    workspaceRoot: input.workspaceRoot,
+                }),
+                name: "xterm-256color",
+                cols: session.columns,
+                rows: session.rows,
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+        session.process = {
+            write: (data) => pty.write(data),
+            kill: (signal) => pty.kill(signal),
+            resize: (columns, rows) => pty.resize(columns, rows),
+        };
+        pty.onData((data) => this.append(session, data));
+        pty.onExit(({ exitCode, signal }) => {
+            this.finish(session, exitCode, signal === 0 ? undefined : String(signal));
+        });
+        this.journal(session, input, pty.pid);
+    }
+    finish(session, exitCode, signal) {
+        if (!session.running)
+            return;
+        session.running = false;
+        session.exitCode = exitCode;
+        session.signal = signal;
+        session.resolveExit();
+        this.unjournal(session);
+        session.cleanupTimer = setTimeout(() => this.sessions.delete(session.id), this.completedSessionTtlMs);
+        session.cleanupTimer.unref();
+    }
+    append(session, output) {
+        session.buffer.append(output);
+    }
+    consume(session, maxOutputTokens) {
+        const limit = boundedInteger(maxOutputTokens, DEFAULT_MAX_OUTPUT_TOKENS, 100_000);
+        const maxCharacters = Math.max(256, limit * 4);
+        const buffered = session.buffer.drain(maxCharacters);
+        return {
+            sessionId: session.running ? session.id : undefined,
+            output: buffered.output,
+            outputTruncated: buffered.truncated,
+            running: session.running,
+            exitCode: session.exitCode,
+            signal: session.signal,
+            wallTimeMs: Date.now() - session.startedAt,
+        };
+    }
+    getOwnedSession(workspaceId, sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            throw new Error(`Unknown process session: ${sessionId}`);
+        if (session.workspaceId !== workspaceId) {
+            throw new Error(`Process session ${sessionId} does not belong to workspace ${workspaceId}.`);
+        }
+        return session;
+    }
+    removeSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        this.unjournal(session);
+        if (session?.cleanupTimer)
+            clearTimeout(session.cleanupTimer);
+        this.sessions.delete(sessionId);
+    }
+    /** Best-effort journal write; never blocks or throws into the spawn path. */
+    journal(session, input, pid) {
+        if (!this.journalDir || !pid || pid <= 1)
+            return;
+        session.journalPid = pid;
+        void import("./process-journal.js").then(({ recordProcessJournal }) => recordProcessJournal(this.journalDir, {
+            pid,
+            pgid: process.platform === "win32" ? undefined : pid,
+            workspaceId: input.workspaceId,
+            workspaceRoot: input.workspaceRoot ?? input.cwd,
+            commandPreview: input.command.slice(0, 120),
+            startedAt: new Date().toISOString(),
+        }).catch(() => undefined)).catch(() => undefined);
+    }
+    unjournal(session) {
+        if (!session || !this.journalDir || !session.journalPid)
+            return;
+        const pid = session.journalPid;
+        session.journalPid = undefined;
+        void import("./process-journal.js").then(({ removeProcessJournal }) => removeProcessJournal(this.journalDir, pid).catch(() => undefined)).catch(() => undefined);
+    }
+}

package/dist/rate-limit.js

@@ -0,0 +1,77 @@
+import { requestIp } from "./logger.js";
+/**
+ * Small in-memory sliding-window limiter. State is per-process by design:
+ * Hearth runs as a single local server process, so this needs no shared
+ * store. Keys that go idle are evicted lazily to keep the map bounded.
+ */
+export class RateLimiter {
+    options;
+    buckets = new Map();
+    lastSweep = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    take(key, now = Date.now()) {
+        this.sweep(now);
+        const bucketKey = `${this.options.keyPrefix}:${key}`;
+        const bucket = this.buckets.get(bucketKey) ?? { hits: [] };
+        const cutoff = now - this.options.rule.windowMs;
+        bucket.hits = bucket.hits.filter((hit) => hit > cutoff);
+        if (bucket.hits.length >= this.options.rule.limit) {
+            const oldest = bucket.hits[0];
+            const retryAfterSeconds = Math.max(1, Math.ceil((oldest + this.options.rule.windowMs - now) / 1000));
+            this.buckets.set(bucketKey, bucket);
+            return { allowed: false, retryAfterSeconds };
+        }
+        bucket.hits.push(now);
+        this.buckets.set(bucketKey, bucket);
+        return { allowed: true, retryAfterSeconds: 0 };
+    }
+    /** Successful authorizations reset the failure window for the key. */
+    reset(key) {
+        this.buckets.delete(`${this.options.keyPrefix}:${key}`);
+    }
+    sweep(now) {
+        if (now - this.lastSweep < 60_000 && this.buckets.size < 10_000)
+            return;
+        this.lastSweep = now;
+        const cutoff = now - this.options.rule.windowMs;
+        for (const [key, bucket] of this.buckets) {
+            if (!bucket.hits.some((hit) => hit > cutoff))
+                this.buckets.delete(key);
+        }
+    }
+}
+export function ipRateLimitMiddleware(limiter, trustProxy) {
+    return (req, res, next) => {
+        const ip = requestIp(req, trustProxy) ?? "unknown";
+        const result = limiter.take(ip);
+        if (result.allowed) {
+            next();
+            return;
+        }
+        res.setHeader("Retry-After", String(result.retryAfterSeconds));
+        res.status(429).json({
+            error: "rate_limited",
+            error_description: "Too many requests. Try again later.",
+        });
+    };
+}
+export const DEFAULT_AUTH_RATE_LIMITS = {
+    authorizeRule: { limit: 20, windowMs: 60 * 60 * 1000 },
+    registerRule: { limit: 30, windowMs: 60 * 60 * 1000 },
+    tokenRule: { limit: 120, windowMs: 60 * 60 * 1000 },
+};
+export function createAuthRateLimiters(trustProxy, config = DEFAULT_AUTH_RATE_LIMITS) {
+    const authorizeLimiter = new RateLimiter({ keyPrefix: "authorize", rule: config.authorizeRule });
+    const registerLimiter = new RateLimiter({ keyPrefix: "register", rule: config.registerRule });
+    const tokenLimiter = new RateLimiter({ keyPrefix: "token", rule: config.tokenRule });
+    return {
+        authorizeLimiter,
+        registerLimiter,
+        tokenLimiter,
+        authorizeIpMiddleware: ipRateLimitMiddleware(authorizeLimiter, trustProxy),
+        registerIpMiddleware: ipRateLimitMiddleware(registerLimiter, trustProxy),
+        tokenIpMiddleware: ipRateLimitMiddleware(tokenLimiter, trustProxy),
+    };
+}

package/dist/request-meta.js

@@ -0,0 +1,9 @@
+function metadataString(meta, key) {
+    if (typeof meta !== "object" || meta === null)
+        return undefined;
+    const value = meta[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function conversationScopeIdFromRequestMeta(meta) {
+    return metadataString(meta, "openai/session");
+}