@sunshinelife83/hearth 1.0.0

package/dist/local-agent-adapters.js

@@ -0,0 +1,20 @@
+import { AcpLocalAgentDriver, resolveAcpCommand, resolveAcpModelConfigUpdate, resolveAcpEffortConfigUpdate, } from "./local-agent-acp.js";
+import { ClaudeLocalAgentDriver, claudeCommandEnvironment, } from "./local-agent-claude.js";
+import { CodexLocalAgentDriver } from "./local-agent-codex.js";
+import { OpencodeLocalAgentDriver, extractOpenCodeFinalResponse, } from "./local-agent-opencode.js";
+import { PiLocalAgentDriver, extractPiFinalResponse, extractPiProviderError, } from "./local-agent-pi.js";
+export function createLocalAgentDrivers(options = {}) {
+    return [
+        new CodexLocalAgentDriver(options.env),
+        new ClaudeLocalAgentDriver(options.claudeQueryFactory, options.env),
+        new OpencodeLocalAgentDriver(options.opencodeFactory),
+        new PiLocalAgentDriver(options.piSessionFactory),
+        new AcpLocalAgentDriver("cursor", options.env),
+        new AcpLocalAgentDriver("copilot", options.env),
+        new AcpLocalAgentDriver("grok", options.env),
+    ];
+}
+export function extractLocalAgentResponseText(value) {
+    return extractOpenCodeFinalResponse(value) || extractPiFinalResponse(value);
+}
+export { claudeCommandEnvironment, extractOpenCodeFinalResponse, extractPiFinalResponse, extractPiProviderError, resolveAcpCommand, resolveAcpModelConfigUpdate, resolveAcpEffortConfigUpdate, };

package/dist/local-agent-availability.js

@@ -0,0 +1,92 @@
+import { accessSync, constants } from "node:fs";
+import { delimiter, resolve } from "node:path";
+import { LOCAL_AGENT_PROVIDERS, } from "./local-agent-profiles.js";
+export function getLocalAgentProviderAvailabilitySnapshot(env = process.env) {
+    return LOCAL_AGENT_PROVIDERS.map((provider) => checkLocalAgentProviderAvailability(provider, env));
+}
+function checkLocalAgentProviderAvailability(provider, env = process.env) {
+    switch (provider) {
+        case "codex":
+            return codexAvailability(env);
+        case "claude":
+            return packageAvailability(provider, "@anthropic-ai/claude-agent-sdk");
+        case "opencode":
+            return packageAvailability(provider, "@opencode-ai/sdk/v2");
+        case "pi":
+            return packageAvailability(provider, "@earendil-works/pi-coding-agent");
+        case "cursor":
+            return commandAvailability(provider, env.CURSOR_COMMAND ?? "cursor-agent", env);
+        case "copilot":
+            return commandAvailability(provider, env.COPILOT_COMMAND ?? "copilot", env);
+        case "grok":
+            return commandAvailability(provider, env.GROK_COMMAND ?? "grok", env);
+    }
+}
+export function assertLocalAgentProviderAvailable(provider, env = process.env) {
+    const availability = checkLocalAgentProviderAvailability(provider, env);
+    if (availability.available)
+        return;
+    throw new Error(`${provider} provider is not available: ${availability.reason ?? "provider preflight failed"}`);
+}
+function packageAvailability(provider, packageName) {
+    try {
+        import.meta.resolve(packageName);
+        return { name: provider, available: true };
+    }
+    catch {
+        return {
+            name: provider,
+            available: false,
+            reason: `${packageName} package not found`,
+        };
+    }
+}
+function codexAvailability(env) {
+    const availability = commandAvailability("codex", env.CODEX_COMMAND ?? "codex", env);
+    return availability.available
+        ? {
+            ...availability,
+            note: "available",
+        }
+        : availability;
+}
+function commandAvailability(provider, command, env) {
+    if (resolveCommand(command, env))
+        return { name: provider, available: true };
+    return {
+        name: provider,
+        available: false,
+        reason: `${command} executable not found`,
+    };
+}
+function resolveCommand(command, env) {
+    if (command.includes("/") || command.includes("\\")) {
+        return executableExists(command) ? command : undefined;
+    }
+    const path = env.PATH;
+    if (!path)
+        return undefined;
+    const extensions = process.platform === "win32"
+        ? ["", ...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)]
+        : [""];
+    for (const directory of path.split(delimiter)) {
+        if (!directory)
+            continue;
+        for (const extension of extensions) {
+            const candidate = resolve(directory, `${command}${extension}`);
+            if (executableExists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function executableExists(command) {
+    const mode = process.platform === "win32" ? constants.F_OK : constants.X_OK;
+    try {
+        accessSync(command, mode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/local-agent-catalog.js

@@ -0,0 +1,51 @@
+import { LOCAL_AGENT_PROVIDERS, } from "./local-agent-profiles.js";
+export function buildLocalAgentProviderStatuses(config, availability) {
+    return LOCAL_AGENT_PROVIDERS.map((id) => {
+        const configured = config.providers.find((entry) => entry.id === id);
+        const live = availability.find((entry) => entry.name === id);
+        const enabled = configured?.enabled === true;
+        const available = live?.available === true;
+        return {
+            id,
+            enabled,
+            available,
+            usable: config.enabled && enabled && available,
+            model: configured?.model,
+            effort: configured?.effort,
+            reason: live?.reason,
+            note: live?.note,
+        };
+    });
+}
+export function buildLocalAgentCatalog(config, profiles, providers) {
+    const visibleProviders = providers.filter((provider) => provider.enabled);
+    const usable = new Map(visibleProviders.filter((provider) => provider.usable).map((provider) => [provider.id, provider]));
+    return {
+        enabled: config.enabled,
+        providers: visibleProviders,
+        profiles: profiles
+            .filter((profile) => !profile.disabled && usable.has(profile.provider))
+            .map((profile) => {
+            const provider = usable.get(profile.provider);
+            return {
+                name: profile.name,
+                description: profile.description,
+                provider: profile.provider,
+                model: profile.model ?? provider.model,
+                effort: profile.effort ?? provider.effort,
+            };
+        }),
+    };
+}
+export function formatLocalAgentProviderStatusSummary(providers) {
+    return providers.map((provider) => {
+        const state = provider.usable
+            ? "usable"
+            : !provider.enabled
+                ? "disabled"
+                : !provider.available
+                    ? `unavailable: ${provider.reason ?? "provider preflight failed"}`
+                    : "subagents disabled";
+        return `${provider.id} (${state})`;
+    }).join(", ");
+}

package/dist/local-agent-claude.js

@@ -0,0 +1,334 @@
+import { AgentProviderExecutionError, AgentProviderProtocolError, AgentProviderUnavailableError, captureAgentProviderResult, isProgrammerDefect, } from "./local-agent-errors.js";
+const CLAUDE_WORKSPACE_ALLOWED_TOOLS = [
+    // allowedTools is passed as a session/CLI rule, so `/` is anchored to the query cwd.
+    "Read(/**)",
+    "Edit(/**)",
+    "Bash",
+];
+class AsyncInputQueue {
+    values = [];
+    waiters = [];
+    closed = false;
+    push(value) {
+        if (this.closed)
+            throw new Error("Claude input stream is closed.");
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter.resolve({ done: false, value });
+        else
+            this.values.push(value);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        while (this.waiters.length > 0)
+            this.waiters.shift().resolve({ done: true, value: undefined });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    next() {
+        const value = this.values.shift();
+        if (value !== undefined)
+            return Promise.resolve({ done: false, value });
+        if (this.closed)
+            return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+    }
+}
+export class ClaudeQueryRuntime {
+    query;
+    inputQueue;
+    provider = "claude";
+    iterator;
+    alive = true;
+    closed = false;
+    providerSessionId;
+    constructor(query, inputQueue, context) {
+        this.query = query;
+        this.inputQueue = inputQueue;
+        this.providerSessionId = context.providerSessionId;
+        this.iterator = query[Symbol.asyncIterator]();
+    }
+    async run(input, callbacks) {
+        return captureAgentProviderResult({
+            provider: "claude",
+            operation: "run",
+            run: async () => {
+                if (!this.isAlive()) {
+                    throw new AgentProviderUnavailableError({
+                        code: "PROVIDER_UNAVAILABLE",
+                        provider: "claude",
+                        operation: "run",
+                        retryable: true,
+                        message: "Claude runtime is not running.",
+                    });
+                }
+                if (this.providerSessionId)
+                    await callbacks?.onSessionId?.(this.providerSessionId);
+                const flagSettings = claudeAuthoritySettings(input.workspaceRoot, input.writeMode);
+                if (input.effort) {
+                    Object.assign(flagSettings, {
+                        alwaysThinkingEnabled: true,
+                        effortLevel: input.effort,
+                    });
+                }
+                await this.query.applyFlagSettings(flagSettings);
+                await this.query.setPermissionMode(claudePermissionMode(input.writeMode));
+                if (input.model && this.query.setModel)
+                    await this.query.setModel(input.model);
+                this.inputQueue.push({
+                    type: "user",
+                    message: { role: "user", content: input.prompt },
+                    parent_tool_use_id: null,
+                });
+                const items = [];
+                for (;;) {
+                    let next;
+                    try {
+                        next = await this.iterator.next();
+                    }
+                    catch (error) {
+                        this.alive = false;
+                        if (isProgrammerDefect(error))
+                            throw error;
+                        throw new AgentProviderUnavailableError({
+                            code: "PROVIDER_UNAVAILABLE",
+                            provider: "claude",
+                            operation: "run",
+                            retryable: true,
+                            cause: error,
+                            message: "Claude query stream failed.",
+                        });
+                    }
+                    if (next.done) {
+                        this.alive = false;
+                        throw new AgentProviderProtocolError({
+                            code: "PROVIDER_PROTOCOL_ERROR",
+                            provider: "claude",
+                            operation: "run",
+                            retryable: true,
+                            message: "Claude query ended before returning a result.",
+                        });
+                    }
+                    const message = next.value;
+                    items.push(message);
+                    const record = asRecord(message);
+                    if (typeof record?.session_id === "string") {
+                        const previousSessionId = this.providerSessionId;
+                        this.providerSessionId = record.session_id;
+                        if (previousSessionId !== this.providerSessionId) {
+                            await callbacks?.onSessionId?.(this.providerSessionId);
+                        }
+                    }
+                    if (record?.type === "assistant") {
+                        const delta = claudeAssistantText(record);
+                        if (delta)
+                            callbacks?.onOutput?.(delta);
+                    }
+                    if (record?.type !== "result")
+                        continue;
+                    const resultError = claudeResultError(record);
+                    if (resultError) {
+                        throw new AgentProviderExecutionError({
+                            code: "PROVIDER_EXECUTION_ERROR",
+                            provider: "claude",
+                            operation: "run",
+                            retryable: false,
+                            cause: new Error(resultError),
+                            message: "Claude agent turn failed.",
+                        });
+                    }
+                    const finalResponse = typeof record.result === "string" ? record.result.trim() : "";
+                    if (!finalResponse) {
+                        throw new AgentProviderProtocolError({
+                            code: "PROVIDER_PROTOCOL_ERROR",
+                            provider: "claude",
+                            operation: "run",
+                            retryable: false,
+                            message: "Claude did not return a final assistant response.",
+                        });
+                    }
+                    return {
+                        provider: this.provider,
+                        providerSessionId: this.providerSessionId ?? null,
+                        finalResponse,
+                        items,
+                    };
+                }
+            },
+        });
+    }
+    async releaseSession(_providerSessionId) {
+        // Claude's streaming query owns the durable session; it remains warm.
+    }
+    isAlive() {
+        return this.alive && !this.closed;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.alive = false;
+        this.inputQueue.close();
+        this.query.close();
+    }
+}
+export class ClaudeLocalAgentDriver {
+    factory;
+    env;
+    provider = "claude";
+    idleTimeoutMs = 3 * 60_000;
+    constructor(factory = defaultClaudeQueryFactory, env = process.env) {
+        this.factory = factory;
+        this.env = env;
+    }
+    runtimeKey(context) {
+        const authority = context.writeMode === "full_access" ? "full_access" : "restricted";
+        return `claude:${context.agentId}:${authority}`;
+    }
+    async createRuntime(context) {
+        return captureAgentProviderResult({
+            provider: this.provider,
+            agentId: context.agentId,
+            operation: "create_runtime",
+            run: async () => {
+                const inputQueue = new AsyncInputQueue();
+                const input = {
+                    prompt: "",
+                    workspaceRoot: context.workspaceRoot,
+                    providerSessionId: context.providerSessionId,
+                    writeMode: context.writeMode,
+                    model: context.model,
+                    effort: context.effort,
+                };
+                const query = await this.factory({
+                    context,
+                    options: claudeQueryOptions(context, input, this.env),
+                    prompt: inputQueue,
+                });
+                return new ClaudeQueryRuntime(query, inputQueue, context);
+            },
+        });
+    }
+}
+async function defaultClaudeQueryFactory({ options, prompt, }) {
+    const { query } = await import("@anthropic-ai/claude-agent-sdk");
+    return query({
+        prompt,
+        options: options,
+    });
+}
+export function claudeQueryOptions(context, input, env = process.env) {
+    const executable = env.CLAUDE_COMMAND;
+    const permissionMode = claudePermissionMode(input.writeMode);
+    const authority = claudeAuthorityOptions(input.workspaceRoot, input.writeMode);
+    return {
+        cwd: input.workspaceRoot,
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.effort ? { thinking: { type: "adaptive" }, effort: input.effort } : {}),
+        ...(context.providerSessionId ? { resume: context.providerSessionId } : {}),
+        permissionMode,
+        // Restricted runtimes stay warm across read_only/allowed turns. Keep the
+        // workspace capabilities static and narrow individual turns with deny rules.
+        ...(input.writeMode === "full_access"
+            ? {}
+            : { allowedTools: [...CLAUDE_WORKSPACE_ALLOWED_TOOLS] }),
+        sandbox: authority.sandbox,
+        settings: authority.settings,
+        ...(input.writeMode === "full_access" ? { allowDangerouslySkipPermissions: true } : {}),
+        env: claudeCommandEnvironment(env),
+        ...(executable ? { pathToClaudeCodeExecutable: executable } : {}),
+    };
+}
+export function claudePermissionMode(writeMode) {
+    switch (writeMode) {
+        case "read_only":
+        case "allowed":
+        case undefined:
+            return "dontAsk";
+        case "full_access": return "bypassPermissions";
+    }
+}
+export function claudeAuthoritySettings(workspaceRoot, writeMode) {
+    return claudeAuthorityOptions(workspaceRoot, writeMode).settings;
+}
+function claudeAuthorityOptions(workspaceRoot, writeMode) {
+    if (writeMode === "full_access") {
+        const sandbox = {
+            enabled: false,
+            allowUnsandboxedCommands: true,
+        };
+        return {
+            sandbox,
+            settings: {
+                permissions: { defaultMode: "bypassPermissions" },
+                sandbox,
+            },
+        };
+    }
+    const allowed = writeMode !== "read_only";
+    const permissions = {
+        defaultMode: "dontAsk",
+        deny: allowed ? [] : ["Bash", "Edit"],
+    };
+    const sandbox = {
+        enabled: true,
+        failIfUnavailable: true,
+        autoAllowBashIfSandboxed: true,
+        allowUnsandboxedCommands: false,
+        filesystem: {
+            allowWrite: allowed ? [workspaceRoot] : [],
+            denyWrite: allowed ? [] : [workspaceRoot],
+        },
+    };
+    return { sandbox, settings: { permissions, sandbox } };
+}
+export function claudeCommandEnvironment(env) {
+    const next = { ...env };
+    for (const key of [
+        "CLAUDECODE",
+        "CLAUDE_CODE_ENTRYPOINT",
+        "CLAUDE_CODE_SSE_PORT",
+        "CLAUDE_AGENT_SDK_VERSION",
+    ]) {
+        delete next[key];
+    }
+    return next;
+}
+export function claudeResultError(record) {
+    const subtype = typeof record.subtype === "string" ? record.subtype : undefined;
+    const isError = record.is_error === true || subtype?.startsWith("error");
+    if (!isError)
+        return undefined;
+    const message = directString(record.error) ??
+        directString(record.message) ??
+        directString(record.result) ??
+        subtype ??
+        "Claude returned an error result.";
+    return `Claude returned an error result: ${message}`;
+}
+function directString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function claudeAssistantText(record) {
+    const content = record.message && typeof record.message === "object"
+        ? record.message.content
+        : undefined;
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const block of content) {
+        const item = block && typeof block === "object" ? block : undefined;
+        if (item?.type === "text" && typeof item.text === "string" && item.text) {
+            parts.push(item.text);
+        }
+    }
+    return parts.length > 0 ? parts.join("") : undefined;
+}