@sunshinelife83/hearth 1.0.0

package/dist/local-agent-daemon-lifecycle.js

@@ -0,0 +1,195 @@
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, closeSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync, } from "node:fs";
+import { join, resolve } from "node:path";
+export const LOCAL_AGENT_DAEMON_PROTOCOL_VERSION = 4;
+export const LOCAL_AGENT_DAEMON_SOCKET_NAME = "agentd.sock";
+export const LOCAL_AGENT_DAEMON_PID_NAME = "agentd.pid";
+export const LOCAL_AGENT_DAEMON_LOCK_NAME = "agentd.lock";
+export const LOCAL_AGENT_DAEMON_SECRET_NAME = "agentd.secret";
+export const LOCAL_AGENT_DAEMON_LOG_NAME = "agentd.log";
+export function localAgentDaemonPaths(stateDir, platform = process.platform) {
+    const resolvedStateDir = resolve(stateDir);
+    const socketPath = join(resolvedStateDir, LOCAL_AGENT_DAEMON_SOCKET_NAME);
+    return {
+        stateDir: resolvedStateDir,
+        socketPath,
+        pidPath: join(resolvedStateDir, LOCAL_AGENT_DAEMON_PID_NAME),
+        lockPath: join(resolvedStateDir, LOCAL_AGENT_DAEMON_LOCK_NAME),
+        secretPath: join(resolvedStateDir, LOCAL_AGENT_DAEMON_SECRET_NAME),
+        logPath: join(resolvedStateDir, LOCAL_AGENT_DAEMON_LOG_NAME),
+        endpoint: platform === "win32"
+            ? `\\\\.\\pipe\\hearth-agentd-${hashStateDir(resolvedStateDir)}`
+            : socketPath,
+    };
+}
+export function ensureLocalAgentDaemonStateDir(stateDir) {
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    chmodSync(stateDir, 0o700);
+}
+export class LocalAgentDaemonAlreadyRunningError extends Error {
+    pid;
+    code = "DAEMON_ALREADY_RUNNING";
+    constructor(pid) {
+        super(pid ? `Local agent daemon is already running (pid ${pid}).` : "Local agent daemon is already running.");
+        this.pid = pid;
+        this.name = "LocalAgentDaemonAlreadyRunningError";
+    }
+}
+export class LocalAgentDaemonLock {
+    paths;
+    acquired = false;
+    constructor(paths) {
+        this.paths = paths;
+    }
+    acquire() {
+        ensureLocalAgentDaemonStateDir(this.paths.stateDir);
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const temporaryPath = `${this.paths.lockPath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+            let published = false;
+            try {
+                writeFileSecure(temporaryPath, `${process.pid}\n`);
+                // Publish the owner record atomically. An empty lock must never be
+                // visible to stale-lock recovery between create and write.
+                linkSync(temporaryPath, this.paths.lockPath);
+                published = true;
+                rmSync(temporaryPath, { force: true });
+                chmodSync(this.paths.lockPath, 0o600);
+                writeFileSecure(this.paths.pidPath, `${process.pid}\n`);
+                this.acquired = true;
+                return;
+            }
+            catch (error) {
+                rmSync(temporaryPath, { force: true });
+                if (published && readDaemonPid(this.paths.lockPath) === process.pid) {
+                    rmSync(this.paths.lockPath, { force: true });
+                }
+                if (!isFileExistsError(error))
+                    throw error;
+                const pid = readDaemonPid(this.paths.lockPath);
+                if (pid !== undefined && isProcessAlive(pid)) {
+                    throw new LocalAgentDaemonAlreadyRunningError(pid);
+                }
+                if (pid === undefined) {
+                    // An undecodable lock may belong to a process that has not finished
+                    // publishing its owner record. Refuse to delete it automatically.
+                    throw new LocalAgentDaemonAlreadyRunningError();
+                }
+                if (!removeStaleLock(this.paths.lockPath))
+                    continue;
+            }
+        }
+        throw new LocalAgentDaemonAlreadyRunningError(readDaemonPid(this.paths.lockPath));
+    }
+    release() {
+        if (!this.acquired)
+            return;
+        this.acquired = false;
+        if (readDaemonPid(this.paths.pidPath) === process.pid) {
+            rmSync(this.paths.pidPath, { force: true });
+        }
+        if (readDaemonPid(this.paths.lockPath) === process.pid) {
+            rmSync(this.paths.lockPath, { force: true });
+        }
+    }
+}
+export function ensureLocalAgentDaemonSecret(paths) {
+    ensureLocalAgentDaemonStateDir(paths.stateDir);
+    try {
+        const secret = readFileSync(paths.secretPath, "utf8").trim();
+        if (isDaemonSecret(secret))
+            return secret;
+    }
+    catch {
+        // Create the secret below.
+    }
+    const secret = randomBytes(32).toString("hex");
+    try {
+        const fileDescriptor = openSync(paths.secretPath, "wx", 0o600);
+        try {
+            writeSync(fileDescriptor, `${secret}\n`);
+            chmodSync(paths.secretPath, 0o600);
+            return secret;
+        }
+        finally {
+            closeSync(fileDescriptor);
+        }
+    }
+    catch (error) {
+        if (!isFileExistsError(error))
+            throw error;
+        const existing = readFileSync(paths.secretPath, "utf8").trim();
+        if (!isDaemonSecret(existing))
+            throw new Error("Local agent daemon secret is invalid.");
+        return existing;
+    }
+}
+export function readLocalAgentDaemonSecret(paths) {
+    try {
+        const secret = readFileSync(paths.secretPath, "utf8").trim();
+        return isDaemonSecret(secret) ? secret : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function removeLocalAgentDaemonFiles(paths) {
+    rmSync(paths.pidPath, { force: true });
+    if (process.platform !== "win32")
+        rmSync(paths.socketPath, { force: true });
+}
+export function readDaemonPid(pidPath) {
+    try {
+        const value = readFileSync(pidPath, "utf8").trim();
+        if (!/^\d+$/.test(value))
+            return undefined;
+        const pid = Number(value);
+        return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function writeFileSecure(path, content) {
+    const fileDescriptor = openSync(path, "w", 0o600);
+    try {
+        writeSync(fileDescriptor, content);
+        chmodSync(path, 0o600);
+    }
+    finally {
+        closeSync(fileDescriptor);
+    }
+}
+function isFileExistsError(error) {
+    return error.code === "EEXIST";
+}
+function removeStaleLock(path) {
+    const stalePath = `${path}.stale-${process.pid}-${randomBytes(8).toString("hex")}`;
+    try {
+        // Rename moves the exact lock we inspected out of the ownership path. If
+        // another contender publishes a new lock after this point, it is never
+        // removed with the stale one.
+        renameSync(path, stalePath);
+        rmSync(stalePath, { force: true });
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function isDaemonSecret(secret) {
+    return /^[0-9a-f]{64}$/i.test(secret);
+}
+function hashStateDir(stateDir) {
+    return createHash("sha256").update(stateDir).digest("hex").slice(0, 24);
+}

package/dist/local-agent-daemon-main.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { loadConfig } from "./config.js";
+import { createLocalAgentDrivers } from "./local-agent-adapters.js";
+import { loadLocalAgentProfiles } from "./local-agent-profiles.js";
+import { LocalAgentDaemon, writeLocalAgentDaemonLog } from "./local-agent-daemon.js";
+import { LocalAgentDaemonAlreadyRunningError, localAgentDaemonPaths, } from "./local-agent-daemon-lifecycle.js";
+import { LocalAgentManager } from "./local-agent-manager.js";
+import { LocalAgentRuntimePool } from "./local-agent-runtime-pool.js";
+import { LocalAgentStore } from "./local-agent-store.js";
+const config = loadConfig();
+const DEFAULT_DAEMON_SHUTDOWN_TIMEOUT_MS = 10_000;
+const paths = localAgentDaemonPaths(config.stateDir);
+const log = (level, event, fields) => writeLocalAgentDaemonLog(paths, level, event, fields);
+const store = new LocalAgentStore(paths.stateDir);
+const manager = new LocalAgentManager({
+    store,
+    drivers: createLocalAgentDrivers(),
+    pool: new LocalAgentRuntimePool({ logger: log }),
+    loadProfiles: (workspaceRoot) => loadLocalAgentProfiles(config, workspaceRoot, { includeDisabled: true }),
+    agentDir: config.agentDir,
+    allowedRoots: config.allowedRoots,
+    logger: log,
+    subagents: config.subagents,
+});
+const daemon = new LocalAgentDaemon({
+    stateDir: paths.stateDir,
+    manager,
+    onLockAcquired: () => {
+        const reconciled = manager.reconcileActiveRuns();
+        if (reconciled.isErr())
+            throw reconciled.error;
+    },
+    onClosed: () => { if (!shuttingDown)
+        process.exit(0); },
+    idleShutdownMs: parseIdleShutdownMs(process.env.HEARTH_AGENTD_IDLE_TIMEOUT_MS),
+});
+let shuttingDown = false;
+const shutdown = () => {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    const forceTimer = setTimeout(() => {
+        log("error", "daemon_forced_shutdown", {
+            activeTurns: manager.activeTurnCount,
+            runtimeCount: manager.runtimeCount,
+        });
+        // Active records intentionally remain durable. The next daemon startup
+        // reconciles them to error while preserving provider continuation data.
+        process.exit(1);
+    }, parseShutdownTimeoutMs(process.env.HEARTH_AGENTD_SHUTDOWN_TIMEOUT_MS));
+    forceTimer.unref();
+    void daemon.close().finally(() => process.exit(0));
+};
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);
+try {
+    await daemon.start();
+}
+catch (error) {
+    if (error instanceof LocalAgentDaemonAlreadyRunningError) {
+        await manager.close();
+        process.exit(0);
+    }
+    log("error", "daemon_start_failed", { error: error instanceof Error ? error.message : String(error) });
+    await manager.close();
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+}
+function parseIdleShutdownMs(value) {
+    if (value === undefined || value.trim() === "")
+        return 30_000;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error("HEARTH_AGENTD_IDLE_TIMEOUT_MS must be a non-negative duration.");
+    }
+    return parsed;
+}
+function parseShutdownTimeoutMs(value) {
+    if (value === undefined || value.trim() === "")
+        return DEFAULT_DAEMON_SHUTDOWN_TIMEOUT_MS;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error("HEARTH_AGENTD_SHUTDOWN_TIMEOUT_MS must be a non-negative duration.");
+    }
+    return parsed;
+}

package/dist/local-agent-daemon-protocol.js

@@ -0,0 +1,302 @@
+import { LOCAL_AGENT_DAEMON_PROTOCOL_VERSION } from "./local-agent-daemon-lifecycle.js";
+export function encodeLocalAgentDaemonRequest(request) {
+    return `${JSON.stringify(request)}\n`;
+}
+export function encodeLocalAgentDaemonResponse(response) {
+    return `${JSON.stringify(response)}\n`;
+}
+export function decodeLocalAgentDaemonRequest(value) {
+    const record = asRecord(value);
+    const requestId = requiredString(record?.requestId, "requestId");
+    const protocolVersion = requiredInteger(record?.protocolVersion, "protocolVersion");
+    const authToken = requiredString(record?.authToken, "authToken");
+    const method = requiredString(record?.method, "method");
+    const params = record?.params;
+    switch (method) {
+        case "hello":
+        case "daemon.status":
+        case "daemon.stop":
+            return { requestId, protocolVersion, authToken, method, params: decodeEmptyParams(params) };
+        case "agent.start":
+            return {
+                requestId,
+                protocolVersion,
+                authToken,
+                method,
+                params: decodeStartInput(params),
+            };
+        case "agent.continue":
+            return {
+                requestId,
+                protocolVersion,
+                authToken,
+                method,
+                params: decodeContinueInput(params),
+            };
+        case "agent.get":
+            return {
+                requestId,
+                protocolVersion,
+                method,
+                authToken,
+                params: {
+                    id: requiredString(asRecord(params)?.id, "id"),
+                    scope: decodeWorkspaceScope(asRecord(params)?.scope),
+                },
+            };
+        case "agent.list":
+            return {
+                requestId,
+                protocolVersion,
+                authToken,
+                method,
+                params: decodeListScope(params),
+            };
+        case "agent.pause":
+        case "agent.stop":
+            return {
+                requestId,
+                protocolVersion,
+                authToken,
+                method,
+                params: decodeLifecycleInput(params),
+            };
+        case "agent.resume":
+            return {
+                requestId,
+                protocolVersion,
+                authToken,
+                method,
+                params: decodeResumeInput(params),
+            };
+        case "daemon.logs":
+            return {
+                requestId,
+                protocolVersion,
+                authToken,
+                method,
+                params: decodeLogsParams(params),
+            };
+        default:
+            throw new LocalAgentDaemonProtocolError("UNKNOWN_METHOD", `Unknown daemon method: ${method}`);
+    }
+}
+export function decodeLocalAgentDaemonResponse(value) {
+    const record = asRecord(value);
+    const requestId = requiredString(record?.requestId, "requestId");
+    const protocolVersion = requiredInteger(record?.protocolVersion, "protocolVersion");
+    if (record?.ok === true) {
+        return { requestId, protocolVersion, ok: true, result: record.result };
+    }
+    if (record?.ok === false) {
+        const error = asRecord(record.error);
+        return {
+            requestId,
+            protocolVersion,
+            ok: false,
+            error: {
+                code: requiredString(error?.code, "error.code"),
+                message: requiredString(error?.message, "error.message"),
+                retryable: optionalBoolean(error?.retryable),
+                provider: optionalString(error?.provider),
+                agentId: optionalString(error?.agentId),
+                workspaceId: optionalString(error?.workspaceId),
+                operation: optionalString(error?.operation),
+                target: optionalString(error?.target),
+            },
+        };
+    }
+    throw new LocalAgentDaemonProtocolError("INVALID_RESPONSE", "Daemon returned an invalid response.");
+}
+export function decodeAgentRecord(value) {
+    const record = asRecord(value);
+    const status = requiredString(record?.status, "status");
+    if (!isLocalAgentStatus(status))
+        throw new LocalAgentDaemonProtocolError("INVALID_RECORD", "Invalid agent status.");
+    return {
+        id: requiredString(record?.id, "id"),
+        workspaceId: optionalString(record?.workspaceId),
+        workspaceRoot: requiredString(record?.workspaceRoot, "workspaceRoot"),
+        profileName: requiredString(record?.profileName, "profileName"),
+        provider: requiredString(record?.provider, "provider"),
+        model: optionalString(record?.model),
+        effort: optionalString(record?.effort),
+        providerSessionId: optionalString(record?.providerSessionId),
+        status,
+        latestResponse: optionalContentString(record?.latestResponse),
+        latestOutput: optionalContentString(record?.latestOutput),
+        error: optionalContentString(record?.error),
+        errorCode: optionalString(record?.errorCode),
+        errorRetryable: optionalBoolean(record?.errorRetryable),
+        createdAt: requiredString(record?.createdAt, "createdAt"),
+        updatedAt: requiredString(record?.updatedAt, "updatedAt"),
+    };
+}
+export function decodeAgentRecordList(value) {
+    if (!Array.isArray(value))
+        throw new LocalAgentDaemonProtocolError("INVALID_RESULT", "Daemon returned an invalid agent list.");
+    return value.map(decodeAgentRecord);
+}
+export function decodeDaemonStatus(value) {
+    const record = asRecord(value);
+    const state = requiredString(record?.state, "state");
+    if (state !== "ready" && state !== "stopping") {
+        throw new LocalAgentDaemonProtocolError("INVALID_RESULT", "Daemon returned an invalid status.");
+    }
+    return {
+        state,
+        protocolVersion: requiredInteger(record?.protocolVersion, "protocolVersion"),
+        pid: requiredInteger(record?.pid, "pid"),
+        endpoint: requiredString(record?.endpoint, "endpoint"),
+        startedAt: requiredString(record?.startedAt, "startedAt"),
+        activeTurns: requiredInteger(record?.activeTurns, "activeTurns"),
+        runtimeCount: requiredInteger(record?.runtimeCount, "runtimeCount"),
+        clientConnections: requiredInteger(record?.clientConnections, "clientConnections"),
+    };
+}
+export function decodeDaemonLogs(value) {
+    if (typeof value !== "string")
+        throw new LocalAgentDaemonProtocolError("INVALID_RESULT", "Daemon returned invalid logs.");
+    return value;
+}
+export class LocalAgentDaemonProtocolError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "LocalAgentDaemonProtocolError";
+    }
+}
+function decodeEmptyParams(value) {
+    if (value === undefined)
+        return {};
+    const record = asRecord(value);
+    if (!record || Object.keys(record).length > 0) {
+        throw new LocalAgentDaemonProtocolError("INVALID_PARAMS", "This daemon method does not accept parameters.");
+    }
+    return {};
+}
+function decodeStartInput(value) {
+    const record = asRecord(value);
+    return {
+        target: requiredString(record?.target, "target"),
+        prompt: requiredContentString(record?.prompt, "prompt"),
+        workspaceRoot: requiredString(record?.workspaceRoot, "workspaceRoot"),
+        workspaceId: optionalString(record?.workspaceId),
+        model: optionalString(record?.model),
+        effort: optionalString(record?.effort),
+        writeMode: decodeWriteMode(record?.writeMode),
+    };
+}
+function decodeContinueInput(value) {
+    const record = asRecord(value);
+    const overrides = asRecord(record?.overrides);
+    return {
+        id: requiredString(record?.id, "id"),
+        prompt: requiredContentString(record?.prompt, "prompt"),
+        scope: decodeWorkspaceScope(record?.scope),
+        ...(overrides ? { overrides: {
+                model: optionalString(overrides.model),
+                effort: optionalString(overrides.effort),
+                writeMode: decodeWriteMode(overrides.writeMode),
+            } } : {}),
+    };
+}
+function decodeWorkspaceScope(value) {
+    const record = asRecord(value);
+    if (!record)
+        throw new LocalAgentDaemonProtocolError("INVALID_PARAMS", "Workspace scope is required.");
+    return {
+        workspaceId: optionalString(record.workspaceId),
+        workspaceRoot: requiredString(record.workspaceRoot, "scope.workspaceRoot"),
+    };
+}
+function decodeListScope(value) {
+    return decodeWorkspaceScope(value);
+}
+function decodeLogsParams(value) {
+    if (value === undefined)
+        return {};
+    const record = asRecord(value);
+    if (!record)
+        throw new LocalAgentDaemonProtocolError("INVALID_PARAMS", "Log options must be an object.");
+    const lines = record.lines;
+    if (lines === undefined)
+        return {};
+    if (typeof lines !== "number" || !Number.isInteger(lines) || lines < 1 || lines > 10_000) {
+        throw new LocalAgentDaemonProtocolError("INVALID_PARAMS", "Log lines must be an integer between 1 and 10000.");
+    }
+    return { lines };
+}
+function decodeLifecycleInput(value) {
+    const record = asRecord(value);
+    return {
+        id: requiredString(record?.id, "id"),
+        scope: decodeWorkspaceScope(record?.scope),
+        force: optionalBoolean(record?.force),
+    };
+}
+function decodeResumeInput(value) {
+    const record = asRecord(value);
+    const overrides = asRecord(record?.overrides);
+    return {
+        id: requiredString(record?.id, "id"),
+        scope: decodeWorkspaceScope(record?.scope),
+        prompt: optionalContentString(record?.prompt),
+        ...(overrides ? { overrides: {
+                model: optionalString(overrides.model),
+                effort: optionalString(overrides.effort),
+                writeMode: decodeWriteMode(overrides.writeMode),
+            } } : {}),
+    };
+}
+function decodeWriteMode(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "read_only" || value === "allowed" || value === "full_access")
+        return value;
+    throw new LocalAgentDaemonProtocolError("INVALID_PARAMS", "Invalid write mode.");
+}
+function isLocalAgentStatus(value) {
+    return value === "starting" || value === "running" || value === "idle" || value === "paused" || value === "error" || value === "stopped";
+}
+function requiredString(value, field) {
+    const result = optionalString(value);
+    if (!result)
+        throw new LocalAgentDaemonProtocolError("INVALID_PARAMS", `Missing ${field}.`);
+    return result;
+}
+function requiredContentString(value, field) {
+    const result = optionalContentString(value);
+    if (result === undefined)
+        throw new LocalAgentDaemonProtocolError("INVALID_PARAMS", `Missing ${field}.`);
+    return result;
+}
+function requiredInteger(value, field) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new LocalAgentDaemonProtocolError("INVALID_PROTOCOL", `Invalid ${field}.`);
+    }
+    return value;
+}
+function optionalString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function optionalContentString(value) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    return value;
+}
+function optionalBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+export function supportedDaemonProtocolVersion() {
+    return LOCAL_AGENT_DAEMON_PROTOCOL_VERSION;
+}