@sunshinelife83/hearth 1.0.0

package/dist/local-agent-pi.js

@@ -0,0 +1,298 @@
+import { join } from "node:path";
+import { AgentProviderExecutionError, AgentProviderProtocolError, AgentProviderUnavailableError, captureAgentProviderResult, } from "./local-agent-errors.js";
+import { createPiSandboxExtension, createPiSandboxModeRef, registerPiSandboxSession, releasePiSandboxSession, updatePiSandboxSession, } from "./local-agent-pi-sandbox.js";
+const PI_READ_ONLY_TOOLS = ["read", "grep", "find", "ls"];
+const PI_WORKSPACE_TOOLS = ["read", "grep", "find", "ls", "edit", "write", "bash"];
+const PI_FULL_ACCESS_TOOLS = [...PI_WORKSPACE_TOOLS];
+const MAX_PI_EVENTS = 10_000;
+export class PiSessionRuntime {
+    session;
+    provider = "pi";
+    unsubscribe;
+    alive = true;
+    closed = false;
+    collectingEvents = false;
+    events = [];
+    constructor(session) {
+        this.session = session;
+        this.unsubscribe = session.subscribe((event) => {
+            if (!this.collectingEvents)
+                return;
+            if (this.events.length >= MAX_PI_EVENTS)
+                this.events.shift();
+            this.events.push(event);
+        });
+    }
+    async run(input, callbacks) {
+        return captureAgentProviderResult({
+            provider: this.provider,
+            operation: "run",
+            run: async () => {
+                if (!this.isAlive()) {
+                    throw new AgentProviderUnavailableError({
+                        code: "PROVIDER_UNAVAILABLE",
+                        provider: this.provider,
+                        operation: "run",
+                        retryable: true,
+                        message: "Pi runtime is not running.",
+                    });
+                }
+                await callbacks?.onSessionId?.(this.session.sessionId);
+                await this.applyOverrides(input);
+                this.events = [];
+                const messageStart = this.session.messages.length;
+                this.collectingEvents = true;
+                try {
+                    await this.session.prompt(input.prompt);
+                }
+                finally {
+                    this.collectingEvents = false;
+                }
+                const currentMessages = this.session.messages.slice(messageStart);
+                const finalResponse = extractPiFinalResponse({ messages: currentMessages });
+                if (!finalResponse) {
+                    const providerError = extractPiProviderError(this.events) || extractPiProviderError(currentMessages);
+                    if (providerError) {
+                        throw new AgentProviderExecutionError({
+                            code: "PROVIDER_EXECUTION_ERROR",
+                            provider: this.provider,
+                            operation: "run",
+                            retryable: false,
+                            cause: new Error(providerError),
+                            message: "Pi agent turn failed.",
+                        });
+                    }
+                    throw new AgentProviderProtocolError({
+                        code: "PROVIDER_PROTOCOL_ERROR",
+                        provider: this.provider,
+                        operation: "run",
+                        retryable: false,
+                        message: "Pi did not return a final assistant response.",
+                    });
+                }
+                return {
+                    provider: this.provider,
+                    providerSessionId: this.session.sessionId,
+                    finalResponse,
+                    items: [...this.events, ...currentMessages],
+                };
+            },
+        });
+    }
+    async releaseSession(_providerSessionId) {
+        // The runtime is already scoped to one logical Pi session.
+    }
+    isAlive() {
+        return this.alive && !this.closed;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.alive = false;
+        this.unsubscribe();
+        try {
+            await releasePiSandboxSession(this.session);
+        }
+        finally {
+            this.session.dispose();
+        }
+    }
+    async applyOverrides(input) {
+        await updatePiSandboxSession(this.session, input.workspaceRoot, input.writeMode ?? "allowed");
+        this.session.setActiveToolsByName([...piToolsForWriteMode(input.writeMode)]);
+        if (input.model) {
+            const model = resolvePiModel(this.session.modelRegistry, input.model);
+            if (!model) {
+                throw new AgentProviderProtocolError({
+                    code: "PROVIDER_PROTOCOL_ERROR",
+                    provider: "pi",
+                    operation: "configure_model",
+                    retryable: false,
+                    message: `Pi model not found: ${input.model}.`,
+                });
+            }
+            await this.session.setModel(model);
+        }
+        if (input.effort) {
+            this.session.setThinkingLevel(input.effort);
+        }
+    }
+}
+export class PiLocalAgentDriver {
+    factory;
+    provider = "pi";
+    idleTimeoutMs = 3 * 60_000;
+    constructor(factory = defaultPiSessionFactory) {
+        this.factory = factory;
+    }
+    runtimeKey(context) {
+        return `pi:${context.agentId}`;
+    }
+    async createRuntime(context) {
+        return captureAgentProviderResult({
+            provider: this.provider,
+            agentId: context.agentId,
+            operation: "create_runtime",
+            run: async () => {
+                const input = {
+                    prompt: "",
+                    workspaceRoot: context.workspaceRoot,
+                    providerSessionId: context.providerSessionId,
+                    writeMode: context.writeMode,
+                    model: context.model,
+                    effort: context.effort,
+                };
+                const session = await this.factory(context, input);
+                return new PiSessionRuntime(session);
+            },
+        });
+    }
+}
+async function defaultPiSessionFactory(context, input) {
+    const { AuthStorage, ModelRegistry, SessionManager, DefaultResourceLoader, createAgentSession, getAgentDir, } = await import("@earendil-works/pi-coding-agent");
+    // Hearth's agentDir is the compatibility directory used for instructions;
+    // Pi keeps its own native auth, model, and session state under getAgentDir().
+    const agentDir = getAgentDir();
+    const authStorage = AuthStorage.create(join(agentDir, "auth.json"));
+    const modelRegistry = ModelRegistry.create(authStorage, join(agentDir, "models.json"));
+    const sessionManager = await resolveSessionManager(SessionManager, input.workspaceRoot, input.providerSessionId);
+    const model = input.model ? resolvePiModel(modelRegistry, input.model) : undefined;
+    if (input.model && !model) {
+        throw new AgentProviderProtocolError({
+            code: "PROVIDER_PROTOCOL_ERROR",
+            provider: "pi",
+            agentId: context.agentId,
+            operation: "configure_model",
+            retryable: false,
+            message: `Pi model not found: ${input.model}.`,
+        });
+    }
+    const modeRef = createPiSandboxModeRef(input.writeMode ?? "allowed");
+    const resourceLoader = new DefaultResourceLoader({
+        cwd: input.workspaceRoot,
+        agentDir,
+        extensionFactories: [createPiSandboxExtension(input.workspaceRoot, modeRef)],
+    });
+    let session;
+    try {
+        const result = await createAgentSession({
+            cwd: input.workspaceRoot,
+            agentDir,
+            authStorage,
+            modelRegistry,
+            sessionManager: sessionManager,
+            resourceLoader,
+            ...(model ? { model: model } : {}),
+            ...(input.effort ? { thinkingLevel: input.effort } : {}),
+            // Keep the full built-in registry available so warm turns can narrow or
+            // broaden active tools without recreating the session.
+            tools: [...PI_FULL_ACCESS_TOOLS],
+        });
+        session = result.session;
+        await registerPiSandboxSession(session, input.workspaceRoot, modeRef, input.writeMode ?? "allowed");
+        session.setActiveToolsByName([...piToolsForWriteMode(input.writeMode)]);
+        return session;
+    }
+    catch (error) {
+        if (session) {
+            try {
+                await releasePiSandboxSession(session);
+            }
+            finally {
+                session.dispose();
+            }
+        }
+        throw error;
+    }
+}
+export function piToolsForWriteMode(writeMode) {
+    switch (writeMode) {
+        case "read_only": return PI_READ_ONLY_TOOLS;
+        case "full_access": return PI_FULL_ACCESS_TOOLS;
+        case "allowed":
+        case undefined:
+            return PI_WORKSPACE_TOOLS;
+    }
+}
+async function resolveSessionManager(SessionManager, workspaceRoot, providerSessionId) {
+    if (!providerSessionId)
+        return SessionManager.create(workspaceRoot);
+    const sessions = await SessionManager.list(workspaceRoot);
+    const match = sessions.find((session) => session.id === providerSessionId);
+    if (!match) {
+        throw new AgentProviderProtocolError({
+            code: "PROVIDER_PROTOCOL_ERROR",
+            provider: "pi",
+            operation: "session",
+            retryable: false,
+            message: `Pi session not found: ${providerSessionId}.`,
+        });
+    }
+    return SessionManager.open(match.path);
+}
+function resolvePiModel(registry, reference) {
+    const separator = reference.indexOf("/");
+    if (separator !== -1) {
+        return registry.find(reference.slice(0, separator), reference.slice(separator + 1));
+    }
+    const all = registry.getAll?.() ?? [];
+    return all.find((model) => asRecord(model)?.id === reference);
+}
+export function extractPiFinalResponse(value) {
+    const root = unwrapProviderPayload(value);
+    const messages = Array.isArray(root) ? root : readArray(root, "messages");
+    if (!messages)
+        return "";
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = asRecord(messages[index]);
+        if (!message || message.role !== "assistant")
+            continue;
+        const content = message.content;
+        if (!Array.isArray(content))
+            continue;
+        const text = content
+            .map((part) => {
+            const record = asRecord(part);
+            return record?.type === "text" && typeof record.text === "string" ? record.text : "";
+        })
+            .filter(Boolean)
+            .join("\n\n")
+            .trim();
+        if (text)
+            return text;
+    }
+    return "";
+}
+export function extractPiProviderError(value) {
+    const root = unwrapProviderPayload(value);
+    if (Array.isArray(root)) {
+        for (let index = root.length - 1; index >= 0; index -= 1) {
+            const error = extractPiProviderError(root[index]);
+            if (error)
+                return error;
+        }
+        return "";
+    }
+    const messages = readArray(root, "messages");
+    if (messages)
+        return extractPiProviderError(messages);
+    const record = asRecord(asRecord(root)?.message ?? root);
+    if (!record)
+        return "";
+    const error = record.errorMessage ?? record.error;
+    return typeof error === "string" ? error.trim() : "";
+}
+function unwrapProviderPayload(value) {
+    const record = asRecord(value);
+    return record ? record.data ?? record.result ?? value : value;
+}
+function readArray(value, key) {
+    const result = asRecord(value)?.[key];
+    return Array.isArray(result) ? result : undefined;
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/dist/local-agent-presentation.js

@@ -0,0 +1,104 @@
+export function presentAgentTargetCatalog(catalog) {
+    return {
+        targets: [
+            ...catalog.providers
+                .filter((provider) => provider.usable)
+                .map((provider) => ({
+                name: provider.id,
+                kind: "provider",
+                ...(provider.model ? { model: provider.model } : {}),
+                ...(provider.effort ? { effort: provider.effort } : {}),
+            })),
+            ...catalog.profiles.map((profile) => ({
+                name: profile.name,
+                kind: "profile",
+                provider: profile.provider,
+                description: profile.description,
+                ...(profile.model ? { model: profile.model } : {}),
+                ...(profile.effort ? { effort: profile.effort } : {}),
+            })),
+        ],
+    };
+}
+export function presentAgentReceipt(record) {
+    return { id: record.id, status: presentAgentStatus(record.status) };
+}
+export function presentAgentSummary(record) {
+    return { ...presentAgentReceipt(record), target: record.profileName };
+}
+export function presentAgentObservation(record) {
+    const receipt = presentAgentReceipt(record);
+    switch (receipt.status) {
+        case "completed":
+            return {
+                ...receipt,
+                status: "completed",
+                ...(record.latestResponse === undefined ? {} : { response: record.latestResponse }),
+            };
+        case "failed":
+            return { ...receipt, status: "failed", error: presentAgentFailure(record) };
+        case "stopped":
+            return {
+                ...receipt,
+                status: "stopped",
+                ...(hasAgentFailure(record) ? { error: presentAgentFailure(record) } : {}),
+            };
+        case "running":
+            return { id: receipt.id, status: "running" };
+    }
+}
+export function formatAgentTargetCatalog(catalog) {
+    if (catalog.targets.length === 0)
+        return "No usable subagent targets.";
+    return catalog.targets.map((target) => {
+        const settings = [
+            target.model ? `model=${target.model}` : undefined,
+            target.effort ? `effort=${target.effort}` : undefined,
+        ].filter(Boolean).join(" ");
+        if (target.kind === "provider") {
+            return `${target.name} [provider]${settings ? ` ${settings}` : ""}`;
+        }
+        return `${target.name} [profile, ${target.provider}]${settings ? ` ${settings}` : ""} - ${target.description}`;
+    }).join("\n");
+}
+export function formatAgentReceipt(receipt) {
+    return `${receipt.id} ${receipt.status}`;
+}
+export function formatAgentSummary(summary) {
+    return `${formatAgentReceipt(summary)} ${summary.target}`;
+}
+export function formatAgentObservation(observation) {
+    const line = formatAgentReceipt(observation);
+    if (observation.status === "completed" && observation.response !== undefined) {
+        return `${line}\n\n${observation.response}`;
+    }
+    if ((observation.status === "failed" || observation.status === "stopped") && observation.error) {
+        const retryable = observation.error.retryable ? " [retryable]" : "";
+        return `${line} ${observation.error.code}: ${observation.error.message}${retryable}`;
+    }
+    return line;
+}
+function presentAgentStatus(status) {
+    switch (status) {
+        case "starting":
+        case "running":
+            return "running";
+        case "idle":
+        case "paused":
+            return "completed";
+        case "error":
+            return "failed";
+        case "stopped":
+            return "stopped";
+    }
+}
+function hasAgentFailure(record) {
+    return record.error !== undefined || record.errorCode !== undefined || record.errorRetryable !== undefined;
+}
+function presentAgentFailure(record) {
+    return {
+        code: record.errorCode ?? "AGENT_FAILED",
+        message: record.error ?? "Subagent failed without an error message.",
+        retryable: record.errorRetryable ?? false,
+    };
+}

package/dist/local-agent-profiles.js

@@ -0,0 +1,127 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const LOCAL_AGENT_PROVIDERS = [
+    "codex",
+    "claude",
+    "opencode",
+    "pi",
+    "cursor",
+    "copilot",
+    "grok",
+];
+const FRONTMATTER_DELIMITER = "---";
+const PROVIDERS = new Set(LOCAL_AGENT_PROVIDERS);
+export async function loadLocalAgentProfiles(config, workspaceRoot, options = {}) {
+    if (!config.subagents.enabled)
+        return [];
+    const profileDirs = [
+        config.hearthAgentsDir,
+        join(workspaceRoot, ".hearth", "agents"),
+    ];
+    const profilesByName = new Map();
+    for (const directory of profileDirs) {
+        for (const profile of await loadProfilesFromDirectory(directory)) {
+            profilesByName.set(profile.name, profile);
+        }
+    }
+    return Array.from(profilesByName.values())
+        .filter((profile) => options.includeDisabled || !profile.disabled)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+async function loadProfilesFromDirectory(directory) {
+    const resolvedDirectory = resolve(directory);
+    if (!existsSync(resolvedDirectory))
+        return [];
+    const entries = await readdir(resolvedDirectory, { withFileTypes: true });
+    const profiles = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith(".md"))
+            continue;
+        const filePath = join(resolvedDirectory, entry.name);
+        try {
+            profiles.push(await loadProfileFile(filePath));
+        }
+        catch (error) {
+            console.warn(`Skipping invalid subagent profile ${filePath}: ${errorMessage(error)}`);
+        }
+    }
+    return profiles;
+}
+async function loadProfileFile(filePath) {
+    const content = await readFile(filePath, "utf8");
+    const parsed = parseFrontmatter(content, filePath);
+    return profileFromFrontmatter(parsed.frontmatter, parsed.body, filePath);
+}
+function parseFrontmatter(content, filePath) {
+    const normalized = content.replace(/^\uFEFF/, "");
+    const lines = normalized.split(/\r?\n/);
+    if (lines[0]?.trim() !== FRONTMATTER_DELIMITER) {
+        throw new Error(`Subagent profile is missing frontmatter: ${filePath}`);
+    }
+    const endIndex = lines.findIndex((line, index) => index > 0 && line.trim() === FRONTMATTER_DELIMITER);
+    if (endIndex === -1) {
+        throw new Error(`Subagent profile frontmatter is not closed: ${filePath}`);
+    }
+    return {
+        frontmatter: parseProfileYaml(lines.slice(1, endIndex).join("\n"), filePath),
+        body: lines.slice(endIndex + 1).join("\n").trim(),
+    };
+}
+function parseProfileYaml(source, filePath) {
+    let parsed;
+    try {
+        parsed = parseYaml(source) ?? {};
+    }
+    catch (error) {
+        throw new Error(`Unable to parse subagent profile frontmatter: ${filePath}: ${errorMessage(error)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Subagent profile frontmatter must be a mapping: ${filePath}`);
+    }
+    return parsed;
+}
+function profileFromFrontmatter(frontmatter, body, filePath) {
+    const name = readString(frontmatter, "name") ?? basename(filePath, ".md");
+    const description = readString(frontmatter, "description");
+    const provider = readProvider(frontmatter, filePath);
+    if (!description) {
+        throw new Error(`Subagent profile is missing description: ${filePath}`);
+    }
+    return {
+        name,
+        description,
+        provider,
+        model: readString(frontmatter, "model"),
+        effort: readString(frontmatter, "effort"),
+        filePath,
+        body,
+        disabled: frontmatter.disabled === true,
+    };
+}
+function readProvider(frontmatter, filePath) {
+    const provider = readString(frontmatter, "provider");
+    if (!provider) {
+        throw new Error(`Subagent profile is missing provider: ${filePath}`);
+    }
+    if (!PROVIDERS.has(provider)) {
+        throw new Error(`Subagent profile provider must be codex, claude, opencode, pi, cursor, copilot, or grok: ${filePath}`);
+    }
+    return provider;
+}
+export function isLocalAgentProvider(value) {
+    return PROVIDERS.has(value);
+}
+function readString(frontmatter, key) {
+    const value = frontmatter[key];
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}