@sunshinelife83/hearth 1.0.0

package/dist/local-agent-errors.js

@@ -0,0 +1,378 @@
+import { matchError, Result, TaggedError, } from "better-result";
+import { isLocalAgentProvider, } from "./local-agent-profiles.js";
+export class AgentTargetError extends TaggedError("AgentTargetError")() {
+}
+export class AgentConflictError extends TaggedError("AgentConflictError")() {
+}
+export class AgentScopeError extends TaggedError("AgentScopeError")() {
+}
+export class AgentProviderUnavailableError extends TaggedError("AgentProviderUnavailableError")() {
+}
+export class AgentProviderCancelledError extends TaggedError("AgentProviderCancelledError")() {
+}
+export class AgentProviderProtocolError extends TaggedError("AgentProviderProtocolError")() {
+}
+export class AgentProviderExecutionError extends TaggedError("AgentProviderExecutionError")() {
+}
+export class AgentDaemonUnavailableError extends TaggedError("AgentDaemonUnavailableError")() {
+}
+export class AgentDaemonStartupError extends TaggedError("AgentDaemonStartupError")() {
+}
+export class AgentDaemonTimeoutError extends TaggedError("AgentDaemonTimeoutError")() {
+}
+export class AgentDaemonProtocolMismatchError extends TaggedError("AgentDaemonProtocolMismatchError")() {
+}
+export class AgentDaemonUnauthorizedError extends TaggedError("AgentDaemonUnauthorizedError")() {
+}
+export class AgentDaemonInvalidRequestError extends TaggedError("AgentDaemonInvalidRequestError")() {
+}
+export class AgentDaemonInvalidResponseError extends TaggedError("AgentDaemonInvalidResponseError")() {
+}
+export class AgentDaemonInternalError extends TaggedError("AgentDaemonInternalError")() {
+}
+export class AgentStoreError extends TaggedError("AgentStoreError")() {
+    constructor(operation, cause, message) {
+        super({
+            code: "AGENT_STORE_ERROR",
+            operation,
+            retryable: false,
+            cause,
+            message: message ?? `Subagent persistence operation failed: ${operation}.`,
+        });
+    }
+}
+export function isAgentProviderError(error) {
+    return AgentProviderUnavailableError.is(error)
+        || AgentProviderCancelledError.is(error)
+        || AgentProviderProtocolError.is(error)
+        || AgentProviderExecutionError.is(error);
+}
+export function isAgentDaemonError(error) {
+    return AgentDaemonUnavailableError.is(error)
+        || AgentDaemonStartupError.is(error)
+        || AgentDaemonTimeoutError.is(error)
+        || AgentDaemonProtocolMismatchError.is(error)
+        || AgentDaemonUnauthorizedError.is(error)
+        || AgentDaemonInvalidRequestError.is(error)
+        || AgentDaemonInvalidResponseError.is(error)
+        || AgentDaemonInternalError.is(error);
+}
+export function isLocalAgentError(error) {
+    return AgentTargetError.is(error)
+        || AgentConflictError.is(error)
+        || AgentScopeError.is(error)
+        || isAgentProviderError(error)
+        || AgentStoreError.is(error)
+        || isAgentDaemonError(error);
+}
+export function toAgentErrorPayload(error) {
+    return matchError(error, {
+        AgentTargetError: targetErrorPayload,
+        AgentConflictError: conflictErrorPayload,
+        AgentScopeError: scopeErrorPayload,
+        AgentProviderUnavailableError: providerErrorPayload,
+        AgentProviderCancelledError: providerErrorPayload,
+        AgentProviderProtocolError: providerErrorPayload,
+        AgentProviderExecutionError: providerErrorPayload,
+        AgentDaemonUnavailableError: daemonErrorPayload,
+        AgentDaemonStartupError: daemonErrorPayload,
+        AgentDaemonTimeoutError: daemonErrorPayload,
+        AgentDaemonProtocolMismatchError: daemonErrorPayload,
+        AgentDaemonUnauthorizedError: daemonErrorPayload,
+        AgentDaemonInvalidRequestError: daemonErrorPayload,
+        AgentDaemonInvalidResponseError: daemonErrorPayload,
+        AgentDaemonInternalError: daemonErrorPayload,
+        AgentStoreError: storeErrorPayload,
+    });
+}
+export function agentErrorFromPayload(payload) {
+    const retryable = payload.retryable ?? false;
+    const provider = payload.provider && isLocalAgentProvider(payload.provider)
+        ? payload.provider
+        : undefined;
+    switch (payload.code) {
+        case "UNKNOWN_TARGET":
+        case "AGENT_NOT_FOUND":
+        case "PROVIDER_DISABLED":
+        case "PROVIDER_NOT_CONFIGURED":
+        case "TARGET_RESOLUTION_FAILED":
+            return new AgentTargetError({
+                code: payload.code,
+                target: payload.target ?? payload.agentId ?? payload.provider ?? "unknown",
+                provider,
+                operation: payload.operation,
+                retryable,
+                message: payload.message,
+            });
+        case "AGENT_CONFLICT":
+            return new AgentConflictError({
+                code: payload.code,
+                agentId: payload.agentId,
+                operation: payload.operation ?? "request",
+                retryable,
+                message: payload.message,
+            });
+        case "WORKSPACE_MISMATCH":
+        case "WORKSPACE_NOT_ALLOWED":
+        case "WORKSPACE_SCOPE_REQUIRED":
+            return new AgentScopeError({
+                code: payload.code,
+                agentId: payload.agentId,
+                workspaceId: payload.workspaceId,
+                operation: payload.operation ?? "request",
+                retryable,
+                message: payload.message,
+            });
+        case "PROVIDER_UNAVAILABLE":
+        case "PROVIDER_CANCELLED":
+        case "PROVIDER_PROTOCOL_ERROR":
+        case "PROVIDER_EXECUTION_ERROR": {
+            if (!provider)
+                return undefined;
+            const fields = {
+                provider,
+                agentId: payload.agentId,
+                operation: payload.operation ?? "run",
+                retryable,
+                message: payload.message,
+            };
+            if (payload.code === "PROVIDER_UNAVAILABLE") {
+                return new AgentProviderUnavailableError({ code: payload.code, ...fields });
+            }
+            if (payload.code === "PROVIDER_CANCELLED") {
+                return new AgentProviderCancelledError({ code: payload.code, ...fields });
+            }
+            if (payload.code === "PROVIDER_PROTOCOL_ERROR") {
+                return new AgentProviderProtocolError({ code: payload.code, ...fields });
+            }
+            return new AgentProviderExecutionError({ code: payload.code, ...fields });
+        }
+        case "AGENT_STORE_ERROR":
+            return new AgentStoreError(payload.operation ?? "request", undefined, payload.message);
+        case "DAEMON_UNAVAILABLE":
+            return new AgentDaemonUnavailableError({
+                code: payload.code,
+                operation: payload.operation ?? "request",
+                retryable,
+                message: payload.message,
+            });
+        case "DAEMON_STARTUP_FAILURE":
+            return new AgentDaemonStartupError({
+                code: payload.code,
+                operation: payload.operation ?? "startup",
+                retryable,
+                message: payload.message,
+            });
+        case "DAEMON_TIMEOUT":
+            return new AgentDaemonTimeoutError({
+                code: payload.code,
+                operation: payload.operation ?? "request",
+                retryable,
+                message: payload.message,
+            });
+        case "DAEMON_PROTOCOL_MISMATCH":
+            return new AgentDaemonProtocolMismatchError({
+                code: payload.code,
+                operation: payload.operation ?? "hello",
+                retryable,
+                message: payload.message,
+            });
+        case "DAEMON_UNAUTHORIZED":
+            return new AgentDaemonUnauthorizedError({
+                code: payload.code,
+                operation: payload.operation ?? "request",
+                retryable,
+                message: payload.message,
+            });
+        case "DAEMON_INVALID_REQUEST":
+            return new AgentDaemonInvalidRequestError({
+                code: payload.code,
+                operation: payload.operation ?? "request",
+                retryable,
+                message: payload.message,
+            });
+        case "DAEMON_INVALID_RESPONSE":
+            return new AgentDaemonInvalidResponseError({
+                code: payload.code,
+                operation: payload.operation ?? "request",
+                retryable,
+                message: payload.message,
+            });
+        case "DAEMON_INTERNAL_ERROR":
+            return new AgentDaemonInternalError({
+                code: payload.code,
+                operation: payload.operation ?? "request",
+                retryable,
+                message: payload.message,
+            });
+        default:
+            return undefined;
+    }
+}
+/**
+ * One-line cause summary for error messages. A bare "execution failed" hides
+ * the actual provider failure from dashboards and reviewers; the bounded
+ * cause text is what makes failures diagnosable.
+ */
+function causeSummary(cause) {
+    const raw = cause instanceof Error ? cause.message : typeof cause === "string" ? cause : undefined;
+    if (!raw)
+        return undefined;
+    const flat = raw.replace(/\s+/g, " ").trim();
+    if (!flat)
+        return undefined;
+    return flat.length > 300 ? `${flat.slice(0, 297)}...` : flat;
+}
+export function providerErrorFromCause(input) {
+    if (isAgentProviderError(input.cause))
+        return input.cause;
+    if (isLocalAgentError(input.cause))
+        return undefined;
+    const unavailable = unavailableCauseKind(input.cause);
+    if (unavailable) {
+        return new AgentProviderUnavailableError({
+            code: "PROVIDER_UNAVAILABLE",
+            provider: input.provider,
+            agentId: input.agentId,
+            operation: input.operation,
+            retryable: unavailable === "transient",
+            cause: input.cause,
+            message: `${displayProvider(input.provider)} provider is unavailable.`,
+        });
+    }
+    if (isProgrammerDefect(input.cause))
+        return undefined;
+    if (isAbortError(input.cause)) {
+        return new AgentProviderCancelledError({
+            code: "PROVIDER_CANCELLED",
+            provider: input.provider,
+            agentId: input.agentId,
+            operation: input.operation,
+            retryable: false,
+            cause: input.cause,
+            message: `${displayProvider(input.provider)} agent turn was cancelled.`,
+        });
+    }
+    return new AgentProviderExecutionError({
+        code: "PROVIDER_EXECUTION_ERROR",
+        provider: input.provider,
+        agentId: input.agentId,
+        operation: input.operation,
+        retryable: false,
+        cause: input.cause,
+        message: causeSummary(input.cause)
+            ? `${displayProvider(input.provider)} agent execution failed: ${causeSummary(input.cause)}`
+            : `${displayProvider(input.provider)} agent execution failed.`,
+    });
+}
+export async function captureAgentProviderResult(input) {
+    try {
+        return Result.ok(await input.run());
+    }
+    catch (cause) {
+        const error = providerErrorFromCause({
+            provider: input.provider,
+            agentId: input.agentId,
+            operation: input.operation,
+            cause,
+        });
+        if (!error)
+            throw cause;
+        return Result.err(error);
+    }
+}
+export function isProgrammerDefect(error) {
+    if (unavailableCauseKind(error))
+        return false;
+    return error instanceof TypeError
+        || error instanceof ReferenceError
+        || error instanceof SyntaxError
+        || error instanceof RangeError
+        || (error instanceof Error && error.name === "AssertionError");
+}
+function isAbortError(error) {
+    return Boolean(error
+        && typeof error === "object"
+        && "name" in error
+        && String(error.name) === "AbortError");
+}
+function unavailableCauseKind(error) {
+    const seen = new Set();
+    let current = error;
+    while (current && typeof current === "object" && !seen.has(current)) {
+        seen.add(current);
+        const code = "code" in current ? String(current.code) : "";
+        if (code === "ENOENT")
+            return "permanent";
+        if (code === "ECONNREFUSED" || code === "ENOTFOUND")
+            return "transient";
+        current = "cause" in current ? current.cause : undefined;
+    }
+    return undefined;
+}
+function displayProvider(provider) {
+    switch (provider) {
+        case "codex": return "Codex";
+        case "claude": return "Claude";
+        case "opencode": return "OpenCode";
+        case "pi": return "Pi";
+        case "cursor": return "Cursor";
+        case "copilot": return "Copilot";
+        case "grok": return "Grok";
+    }
+}
+function targetErrorPayload(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+        target: error.target,
+        ...(error.provider ? { provider: error.provider } : {}),
+        ...(error.operation ? { operation: error.operation } : {}),
+    };
+}
+function conflictErrorPayload(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+        operation: error.operation,
+        ...(error.agentId ? { agentId: error.agentId } : {}),
+    };
+}
+function scopeErrorPayload(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+        operation: error.operation,
+        ...(error.agentId ? { agentId: error.agentId } : {}),
+        ...(error.workspaceId ? { workspaceId: error.workspaceId } : {}),
+    };
+}
+function providerErrorPayload(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+        provider: error.provider,
+        operation: error.operation,
+        ...(error.agentId ? { agentId: error.agentId } : {}),
+    };
+}
+function daemonErrorPayload(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+        operation: error.operation,
+    };
+}
+function storeErrorPayload(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+        operation: error.operation,
+    };
+}

package/dist/local-agent-grok.js

@@ -0,0 +1,202 @@
+import { AgentProviderProtocolError } from "./local-agent-errors.js";
+export const GROK_DEFAULT_MODEL = "grok-build";
+export const GROK_REASONING_EFFORTS = [
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+const COMPLETED_PROMPT_ID_LIMIT = 128;
+/**
+ * Owns the one ordering-sensitive xAI completion bridge. Grok may resolve the
+ * standard session/prompt request or emit its private completion notification;
+ * whichever arrives first settles the turn, while duplicate and stale events
+ * are bounded and ignored.
+ */
+export class GrokPromptCompletionRegistry {
+    pending = new Map();
+    completedPromptIds = [];
+    wait(sessionId, promptId, timeoutMs, onTimeout) {
+        const key = promptKey(sessionId, promptId);
+        if (this.pending.has(key)) {
+            throw new Error(`Grok prompt completion is already pending: ${promptId}`);
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(key);
+                reject(onTimeout());
+            }, timeoutMs);
+            timer.unref();
+            this.pending.set(key, { sessionId, promptId, resolve, reject, timer });
+        });
+    }
+    resolve(completion) {
+        if (completion.promptId && this.completedPromptIds.includes(completion.promptId))
+            return;
+        const pending = completion.promptId
+            ? this.pending.get(promptKey(completion.sessionId, completion.promptId))
+            : findPendingForSession(this.pending, completion.sessionId);
+        if (!pending)
+            return;
+        this.pending.delete(promptKey(pending.sessionId, pending.promptId));
+        clearTimeout(pending.timer);
+        this.rememberCompletedPromptId(completion.promptId ?? pending.promptId);
+        pending.resolve({ ...completion, promptId: completion.promptId ?? pending.promptId });
+    }
+    remove(sessionId, promptId) {
+        const key = promptKey(sessionId, promptId);
+        const pending = this.pending.get(key);
+        if (!pending)
+            return;
+        this.pending.delete(key);
+        clearTimeout(pending.timer);
+    }
+    rejectAll(error) {
+        const pending = Array.from(this.pending.values());
+        this.pending.clear();
+        for (const entry of pending) {
+            clearTimeout(entry.timer);
+            entry.reject(error);
+        }
+    }
+    markCompleted(sessionId, promptId) {
+        const key = promptKey(sessionId, promptId);
+        const pending = this.pending.get(key);
+        if (pending) {
+            this.pending.delete(key);
+            clearTimeout(pending.timer);
+        }
+        this.rememberCompletedPromptId(promptId);
+    }
+    get size() {
+        return this.pending.size;
+    }
+    rememberCompletedPromptId(promptId) {
+        if (this.completedPromptIds.includes(promptId))
+            return;
+        this.completedPromptIds.push(promptId);
+        if (this.completedPromptIds.length > COMPLETED_PROMPT_ID_LIMIT) {
+            this.completedPromptIds.splice(0, this.completedPromptIds.length - COMPLETED_PROMPT_ID_LIMIT);
+        }
+    }
+}
+export function parseGrokPromptCompletion(input) {
+    const record = asRecord(input);
+    const sessionId = directString(record?.sessionId);
+    if (!sessionId)
+        return undefined;
+    const update = asRecord(record?.update);
+    const sessionUpdate = directString(update?.sessionUpdate);
+    if (update && sessionUpdate !== "turn_completed")
+        return undefined;
+    const promptId = firstString(record?.promptId, record?.requestId, update?.promptId, update?.requestId, asRecord(record?._meta)?.promptId, asRecord(update?._meta)?.promptId);
+    if (promptId && isBackgroundPromptId(promptId))
+        return undefined;
+    return {
+        sessionId,
+        ...(promptId ? { promptId } : {}),
+        ...((firstString(record?.stopReason, update?.stopReason))
+            ? { stopReason: firstString(record?.stopReason, update?.stopReason) }
+            : {}),
+    };
+}
+export function readGrokSessionState(value) {
+    const record = asRecord(value);
+    const response = asRecord(record?.newSessionResponse) ?? record;
+    const models = asRecord(response?.models)
+        ?? asRecord(asRecord(response?._meta)?.modelState);
+    if (!models)
+        return undefined;
+    const availableModels = (readArray(models.availableModels) ?? [])
+        .map(readGrokModelInfo)
+        .filter((model) => model !== undefined);
+    return {
+        currentModelId: directString(models.currentModelId),
+        availableModels,
+    };
+}
+export function normalizeGrokModelId(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.replace(/^(?:grok|xai)\//i, "");
+}
+export function resolveGrokModelId(requested, state) {
+    const modelId = normalizeGrokModelId(requested);
+    if (!modelId)
+        throw grokConfigurationError("Grok model must not be empty.");
+    const available = state?.availableModels ?? [];
+    if (available.length > 0 && !available.some((model) => model.id === modelId)) {
+        throw grokConfigurationError(`Grok does not support '${modelId}'. Available models: ${available.map((model) => model.id).join(", ")}.`);
+    }
+    return modelId;
+}
+export function resolveGrokEffort(effort, state, modelId) {
+    const normalized = effort.trim().toLowerCase();
+    if (!isGrokReasoningEffort(normalized)) {
+        throw grokConfigurationError(`Grok reasoning effort must be one of: ${GROK_REASONING_EFFORTS.join(", ")}.`);
+    }
+    const selectedModel = state?.availableModels.find((model) => model.id === modelId);
+    const availableEfforts = selectedModel?.reasoningEfforts ?? [];
+    if (availableEfforts.length > 0 && !availableEfforts.includes(normalized)) {
+        throw grokConfigurationError(`Grok model '${modelId ?? GROK_DEFAULT_MODEL}' does not support effort '${normalized}'. Available efforts: ${availableEfforts.join(", ")}.`);
+    }
+    return normalized;
+}
+function grokConfigurationError(message) {
+    return new AgentProviderProtocolError({
+        code: "PROVIDER_PROTOCOL_ERROR",
+        provider: "grok",
+        operation: "configure_session",
+        retryable: false,
+        message,
+    });
+}
+export function isGrokReasoningEffort(value) {
+    return GROK_REASONING_EFFORTS.includes(value);
+}
+function readGrokModelInfo(value) {
+    const record = asRecord(value);
+    const id = directString(record?.modelId) ?? directString(record?.id);
+    if (!id)
+        return undefined;
+    const modelMeta = asRecord(record?._meta);
+    const reasoningEfforts = (readArray(modelMeta?.reasoningEfforts) ?? [])
+        .flatMap((entry) => {
+        const effort = asRecord(entry);
+        return [directString(effort?.id), directString(effort?.value)].filter((value) => value !== undefined);
+    })
+        .filter((effort, index, values) => values.indexOf(effort) === index);
+    return { id, reasoningEfforts };
+}
+function findPendingForSession(pending, sessionId) {
+    return Array.from(pending.values()).find((entry) => entry.sessionId === sessionId);
+}
+function promptKey(sessionId, promptId) {
+    return `${sessionId}\u0000${promptId}`;
+}
+function isBackgroundPromptId(promptId) {
+    return /^(?:task|subagent|background)(?:-|_)/i.test(promptId)
+        || /^task-completed-/i.test(promptId);
+}
+function firstString(...values) {
+    for (const value of values) {
+        const result = directString(value);
+        if (result)
+            return result;
+    }
+    return undefined;
+}
+function readArray(value) {
+    return Array.isArray(value) ? value : undefined;
+}
+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;
+}