@elizaos/agent 2.0.0-alpha.97 → 2.0.0-beta.1

package/dist/packages/agent/src/contracts/onboarding-provider-defaults.js

@@ -0,0 +1,202 @@
+import { registerProviderOption } from "@elizaos/shared";
+export const DEFAULT_ONBOARDING_PROVIDER_OPTIONS = [
+    {
+        id: "elizacloud",
+        name: "Eliza Cloud",
+        envKey: null,
+        pluginName: "@elizaos/plugin-elizacloud",
+        keyPrefix: null,
+        description: "Managed hosting for Eliza agents and bundled infrastructure.",
+        family: "elizacloud",
+        authMode: "cloud",
+        group: "cloud",
+        order: 10,
+        recommended: true,
+    },
+    {
+        id: "anthropic-subscription",
+        name: "Claude Subscription",
+        envKey: null,
+        pluginName: "@elizaos/plugin-anthropic",
+        keyPrefix: null,
+        description: "Powers task agents via Claude Code CLI. For the main agent, use Eliza Cloud or a direct API key.",
+        family: "anthropic",
+        authMode: "subscription",
+        group: "subscription",
+        order: 20,
+        recommended: true,
+        labelKey: "providerswitcher.claudeSubscription",
+        storedProvider: "anthropic-subscription",
+    },
+    {
+        id: "openai-subscription",
+        name: "ChatGPT Subscription",
+        envKey: null,
+        pluginName: "@elizaos/plugin-openai",
+        keyPrefix: null,
+        description: "Use your ChatGPT Plus or Pro subscription via OAuth.",
+        family: "openai",
+        authMode: "subscription",
+        group: "subscription",
+        order: 30,
+        recommended: true,
+        labelKey: "providerswitcher.chatgptSubscription",
+        storedProvider: "openai-codex",
+    },
+    {
+        id: "anthropic",
+        name: "Anthropic",
+        envKey: "ANTHROPIC_API_KEY",
+        pluginName: "@elizaos/plugin-anthropic",
+        keyPrefix: "sk-ant-",
+        description: "Claude models via API key.",
+        family: "anthropic",
+        authMode: "api-key",
+        group: "local",
+        order: 50,
+    },
+    {
+        id: "openai",
+        name: "OpenAI",
+        envKey: "OPENAI_API_KEY",
+        pluginName: "@elizaos/plugin-openai",
+        keyPrefix: "sk-",
+        description: "GPT models via API key.",
+        family: "openai",
+        authMode: "api-key",
+        group: "local",
+        order: 60,
+    },
+    {
+        id: "openrouter",
+        name: "OpenRouter",
+        envKey: "OPENROUTER_API_KEY",
+        pluginName: "@elizaos/plugin-openrouter",
+        keyPrefix: "sk-or-",
+        description: "Access multiple models via one API key.",
+        family: "openrouter",
+        authMode: "api-key",
+        group: "local",
+        order: 70,
+        supportsPrimaryModelOverride: true,
+    },
+    {
+        id: "gemini",
+        name: "Gemini",
+        envKey: "GOOGLE_GENERATIVE_AI_API_KEY",
+        pluginName: "@elizaos/plugin-google-genai",
+        keyPrefix: null,
+        description: "Google's Gemini models.",
+        family: "gemini",
+        authMode: "api-key",
+        group: "local",
+        order: 80,
+    },
+    {
+        id: "grok",
+        name: "xAI (Grok)",
+        envKey: "XAI_API_KEY",
+        pluginName: "@elizaos/plugin-xai",
+        keyPrefix: "xai-",
+        description: "xAI's Grok models.",
+        family: "grok",
+        authMode: "api-key",
+        group: "local",
+        order: 90,
+    },
+    {
+        id: "groq",
+        name: "Groq",
+        envKey: "GROQ_API_KEY",
+        pluginName: "@elizaos/plugin-groq",
+        keyPrefix: "gsk_",
+        description: "Fast inference.",
+        family: "groq",
+        authMode: "api-key",
+        group: "local",
+        order: 100,
+    },
+    {
+        id: "deepseek",
+        name: "DeepSeek",
+        envKey: "DEEPSEEK_API_KEY",
+        pluginName: "@elizaos/plugin-deepseek",
+        keyPrefix: "sk-",
+        description: "DeepSeek models.",
+        family: "deepseek",
+        authMode: "api-key",
+        group: "local",
+        order: 110,
+    },
+    {
+        id: "mistral",
+        name: "Mistral",
+        envKey: "MISTRAL_API_KEY",
+        pluginName: "@elizaos/plugin-mistral",
+        keyPrefix: null,
+        description: "Mistral AI models.",
+        family: "mistral",
+        authMode: "api-key",
+        group: "local",
+        order: 120,
+    },
+    {
+        id: "together",
+        name: "Together AI",
+        envKey: "TOGETHER_API_KEY",
+        pluginName: "@elizaos/plugin-together",
+        keyPrefix: null,
+        description: "Open-source model hosting.",
+        family: "together",
+        authMode: "api-key",
+        group: "local",
+        order: 130,
+    },
+    {
+        id: "ollama",
+        name: "Ollama",
+        envKey: null,
+        pluginName: "@elizaos/plugin-ollama",
+        keyPrefix: null,
+        description: "Local models, no API key needed.",
+        family: "ollama",
+        authMode: "local",
+        group: "local",
+        order: 140,
+    },
+    {
+        id: "zai",
+        name: "z.ai",
+        envKey: "ZAI_API_KEY",
+        pluginName: "@homunculuslabs/plugin-zai",
+        keyPrefix: null,
+        description: "GLM models via z.ai Coding Plan.",
+        family: "zai",
+        authMode: "api-key",
+        group: "local",
+        order: 150,
+    },
+    {
+        id: "moonshot",
+        name: "Kimi / Moonshot",
+        envKey: "MOONSHOT_API_KEY",
+        pluginName: "@elizaos/plugin-openai",
+        keyPrefix: "sk-",
+        description: "Kimi models via Moonshot's OpenAI-compatible API.",
+        family: "moonshot",
+        authMode: "api-key",
+        group: "local",
+        order: 160,
+        supportsPrimaryModelOverride: true,
+    },
+];
+let builtInProviderOptionsRegistered = false;
+export function registerBuiltInOnboardingProviderOptions() {
+    if (builtInProviderOptionsRegistered) {
+        return;
+    }
+    for (const option of DEFAULT_ONBOARDING_PROVIDER_OPTIONS) {
+        registerProviderOption({ ...option });
+    }
+    builtInProviderOptionsRegistered = true;
+}

package/dist/packages/agent/src/diagnostics/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./integration-observability.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/packages/agent/src/diagnostics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/diagnostics/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC"}

package/dist/packages/agent/src/diagnostics/index.js

@@ -0,0 +1 @@
+export * from "./integration-observability.js";

package/dist/packages/agent/src/diagnostics/integration-observability.d.ts

@@ -0,0 +1,40 @@
+export type IntegrationBoundary = "cloud" | "wallet" | "marketplace" | "mcp" | "lifeops" | "browser-bridge";
+export type IntegrationOutcome = "success" | "failure";
+export interface IntegrationObservabilityEvent {
+    schema: "integration_boundary_v1";
+    boundary: IntegrationBoundary;
+    operation: string;
+    outcome: IntegrationOutcome;
+    durationMs: number;
+    timeoutMs?: number;
+    statusCode?: number;
+    errorKind?: string;
+}
+interface IntegrationLogger {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+}
+interface IntegrationSpanMeta {
+    boundary: IntegrationBoundary;
+    operation: string;
+    timeoutMs?: number;
+}
+interface IntegrationSpanSuccessArgs {
+    statusCode?: number;
+}
+interface IntegrationSpanFailureArgs {
+    statusCode?: number;
+    error?: unknown;
+    errorKind?: string;
+}
+interface CreateSpanOptions {
+    now?: () => number;
+    sink?: IntegrationLogger;
+}
+export interface IntegrationTelemetrySpan {
+    success: (args?: IntegrationSpanSuccessArgs) => void;
+    failure: (args?: IntegrationSpanFailureArgs) => void;
+}
+export declare function createIntegrationTelemetrySpan(meta: IntegrationSpanMeta, options?: CreateSpanOptions): IntegrationTelemetrySpan;
+export {};
+//# sourceMappingURL=integration-observability.d.ts.map

package/dist/packages/agent/src/diagnostics/integration-observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-observability.d.ts","sourceRoot":"","sources":["../../../../../src/diagnostics/integration-observability.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAC3B,OAAO,GACP,QAAQ,GACR,aAAa,GACb,KAAK,GACL,SAAS,GACT,gBAAgB,CAAC;AACrB,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,yBAAyB,CAAC;IAClC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,iBAAiB;IACzB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,0BAA0B;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,0BAA0B;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,iBAAiB;IACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACrD,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,0BAA0B,KAAK,IAAI,CAAC;CACtD;AAuDD,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,mBAAmB,EACzB,OAAO,GAAE,iBAAsB,GAC9B,wBAAwB,CA2C1B"}

package/dist/packages/agent/src/diagnostics/integration-observability.js

@@ -0,0 +1,78 @@
+import { logger } from "@elizaos/core";
+const EVENT_PREFIX = "[integration]";
+function inferErrorKind(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        if (error.name === "AbortError" ||
+            error.name === "TimeoutError" ||
+            message.includes("timeout") ||
+            message.includes("timed out")) {
+            return "timeout";
+        }
+        return sanitizeToken(error.name);
+    }
+    if (typeof error === "string")
+        return sanitizeToken(error);
+    return undefined;
+}
+function sanitizeToken(value) {
+    if (!value)
+        return undefined;
+    const safe = value.length > 1024 ? value.slice(0, 1024) : value;
+    const token = safe.toLowerCase().replace(/[^a-z0-9_-]/g, "_");
+    const normalized = token
+        .replace(/_{1,1024}/g, "_")
+        .replace(/^_{1,1024}|_{1,1024}$/g, "");
+    return normalized ? normalized.slice(0, 64) : undefined;
+}
+function emitEvent(sink, event) {
+    const line = `${EVENT_PREFIX} ${JSON.stringify(event)}`;
+    if (event.outcome === "success" || isExpectedTransientFailure(event)) {
+        sink.info(line);
+        return;
+    }
+    sink.warn(line);
+}
+function isExpectedTransientFailure(event) {
+    return (event.outcome === "failure" &&
+        event.boundary === "lifeops" &&
+        (event.errorKind === "runtime_unavailable" ||
+            event.errorKind === "lifeops_storage_unavailable" ||
+            event.errorKind === "lifeops_auth_invalid"));
+}
+export function createIntegrationTelemetrySpan(meta, options = {}) {
+    const now = options.now ?? Date.now;
+    const sink = options.sink ?? logger;
+    const startedAt = now();
+    let settled = false;
+    const finalize = (outcome, args) => {
+        if (settled)
+            return;
+        settled = true;
+        const durationMs = Math.max(0, now() - startedAt);
+        const event = {
+            schema: "integration_boundary_v1",
+            boundary: meta.boundary,
+            operation: meta.operation,
+            outcome,
+            durationMs,
+        };
+        if (typeof meta.timeoutMs === "number") {
+            event.timeoutMs = meta.timeoutMs;
+        }
+        if (typeof args?.statusCode === "number") {
+            event.statusCode = args.statusCode;
+        }
+        if (outcome === "failure") {
+            const failureArgs = args;
+            event.errorKind =
+                sanitizeToken(failureArgs?.errorKind) ??
+                    inferErrorKind(failureArgs?.error);
+        }
+        emitEvent(sink, event);
+    };
+    return {
+        success: (args) => finalize("success", args),
+        failure: (args) => finalize("failure", args),
+    };
+}

package/dist/packages/agent/src/hooks/discovery.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Discover hooks from workspace, managed (~/.eliza/hooks/), and bundled dirs.
+ * Later sources win on name conflicts.
+ */
+import type { HookEntry } from "./types.ts";
+export interface DiscoveryOptions {
+    workspacePath?: string;
+    bundledDir?: string;
+    extraDirs?: string[];
+}
+/** Precedence: extra (lowest) -> bundled -> managed -> workspace (highest). */
+export declare function discoverHooks(options?: DiscoveryOptions): Promise<HookEntry[]>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/packages/agent/src/hooks/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/discovery.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAGV,SAAS,EAGV,MAAM,YAAY,CAAC;AA8KpB,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,+EAA+E;AAC/E,wBAAsB,aAAa,CACjC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,SAAS,EAAE,CAAC,CAuCtB"}

package/dist/packages/agent/src/hooks/discovery.js

@@ -0,0 +1,191 @@
+/**
+ * Discover hooks from workspace, managed (~/.eliza/hooks/), and bundled dirs.
+ * Later sources win on name conflicts.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { logger } from "@elizaos/core";
+const HOOK_MD = "HOOK.md";
+const HANDLER_NAMES = [
+    "handler.ts",
+    "handler.mjs",
+    "handler",
+    "index.ts",
+    "index.mjs",
+    "index",
+];
+function parseFrontmatter(content) {
+    const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!fmMatch)
+        return null;
+    const fmBlock = fmMatch[1];
+    const result = { name: "", description: "" };
+    for (const line of fmBlock.split("\n")) {
+        const kvMatch = line.match(/^(\w+):\s*(.+)/);
+        if (!kvMatch)
+            continue;
+        const [, key, rawValue] = kvMatch;
+        const value = rawValue.replace(/^["']|["']$/g, "").trim();
+        switch (key) {
+            case "name":
+                result.name = value;
+                break;
+            case "description":
+                result.description = value;
+                break;
+            case "homepage":
+                result.homepage = value;
+                break;
+            case "metadata":
+                try {
+                    const metaStart = fmBlock.indexOf("metadata:");
+                    if (metaStart !== -1) {
+                        const metaRest = fmBlock
+                            .slice(metaStart + "metadata:".length)
+                            .trim();
+                        const jsonMatch = metaRest.match(/\{[\s\S]*\}/);
+                        if (jsonMatch) {
+                            result.metadata = JSON.parse(jsonMatch[0]);
+                        }
+                    }
+                }
+                catch {
+                    try {
+                        result.metadata = JSON.parse(value);
+                    }
+                    catch {
+                        logger.warn(`[hooks] Failed to parse metadata in HOOK.md`);
+                    }
+                }
+                break;
+        }
+    }
+    return result.name ? result : null;
+}
+function extractMetadata(frontmatter) {
+    const meta = frontmatter.metadata?.eliza;
+    if (!meta)
+        return undefined;
+    return {
+        always: meta.always,
+        hookKey: meta.hookKey,
+        emoji: meta.emoji,
+        homepage: meta.homepage ?? frontmatter.homepage,
+        events: Array.isArray(meta.events) ? meta.events : [],
+        export: meta.export,
+        os: meta.os,
+        requires: meta.requires,
+        install: meta.install,
+    };
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function fileExists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function findHandlerPath(dir) {
+    for (const name of HANDLER_NAMES) {
+        const p = join(dir, name);
+        if (await fileExists(p))
+            return p;
+    }
+    return null;
+}
+async function loadHookFromDir(dir, source, pluginId) {
+    const hookMdPath = join(dir, HOOK_MD);
+    if (!(await fileExists(hookMdPath)))
+        return null;
+    const handlerPath = await findHandlerPath(dir);
+    if (!handlerPath) {
+        logger.warn(`[hooks] Hook at ${dir} has HOOK.md but no handler`);
+        return null;
+    }
+    try {
+        const content = await readFile(hookMdPath, "utf-8");
+        const frontmatter = parseFrontmatter(content);
+        if (!frontmatter) {
+            logger.warn(`[hooks] Invalid frontmatter in ${hookMdPath}`);
+            return null;
+        }
+        const metadata = extractMetadata(frontmatter);
+        const hook = {
+            name: frontmatter.name,
+            description: frontmatter.description,
+            source,
+            pluginId,
+            filePath: hookMdPath,
+            baseDir: dir,
+            handlerPath,
+        };
+        return { hook, frontmatter, metadata };
+    }
+    catch (err) {
+        const msg = String(err);
+        logger.warn(`[hooks] Error loading hook from ${dir}: ${msg}`);
+        return null;
+    }
+}
+async function scanHooksDir(dir, source) {
+    if (!(await isDirectory(dir)))
+        return [];
+    const entries = [];
+    try {
+        const items = await readdir(dir);
+        for (const item of items) {
+            const itemPath = join(dir, item);
+            if (!(await isDirectory(itemPath)))
+                continue;
+            const entry = await loadHookFromDir(itemPath, source);
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+    }
+    catch (err) {
+        const msg = String(err);
+        logger.warn(`[hooks] Error scanning ${dir}: ${msg}`);
+    }
+    return entries;
+}
+/** Precedence: extra (lowest) -> bundled -> managed -> workspace (highest). */
+export async function discoverHooks(options = {}) {
+    const seen = new Map();
+    if (options.extraDirs) {
+        for (const dir of options.extraDirs) {
+            const resolved = resolve(dir.replace(/^~/, homedir()));
+            for (const entry of await scanHooksDir(resolved, "eliza-managed")) {
+                seen.set(entry.hook.name, entry);
+            }
+        }
+    }
+    if (options.bundledDir) {
+        for (const entry of await scanHooksDir(options.bundledDir, "eliza-bundled")) {
+            seen.set(entry.hook.name, entry);
+        }
+    }
+    const managedDir = join(homedir(), ".eliza", "hooks");
+    for (const entry of await scanHooksDir(managedDir, "eliza-managed")) {
+        seen.set(entry.hook.name, entry);
+    }
+    if (options.workspacePath) {
+        const wsHooksDir = join(options.workspacePath.replace(/^~/, homedir()), "hooks");
+        for (const entry of await scanHooksDir(wsHooksDir, "eliza-workspace")) {
+            seen.set(entry.hook.name, entry);
+        }
+    }
+    const all = Array.from(seen.values());
+    logger.info(`[hooks] Discovered ${all.length} hooks`);
+    return all;
+}

package/dist/packages/agent/src/hooks/eligibility.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hook eligibility: checks OS, binary, env, and config requirements.
+ */
+import type { HookConfig, InternalHooksConfig } from "../config/types.hooks.ts";
+import type { ElizaHookMetadata } from "./types.ts";
+export interface EligibilityResult {
+    eligible: boolean;
+    missing: string[];
+}
+export declare function checkEligibility(metadata: ElizaHookMetadata | undefined, hookConfig: HookConfig | undefined, elizaConfig?: Record<string, unknown>): EligibilityResult;
+export declare function resolveHookConfig(internalConfig: InternalHooksConfig | undefined, hookKey: string): HookConfig | undefined;
+//# sourceMappingURL=eligibility.d.ts.map

package/dist/packages/agent/src/hooks/eligibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/eligibility.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAuEpD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACxC,iBAAiB,CAyDnB;AAED,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,mBAAmB,GAAG,SAAS,EAC/C,OAAO,EAAE,MAAM,GACd,UAAU,GAAG,SAAS,CAExB"}

package/dist/packages/agent/src/hooks/eligibility.js

@@ -0,0 +1,105 @@
+/**
+ * Hook eligibility: checks OS, binary, env, and config requirements.
+ */
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+import { delimiter, dirname, extname, isAbsolute, join } from "node:path";
+function binaryExists(name) {
+    const pathExts = process.platform === "win32"
+        ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM")
+            .split(";")
+            .map((ext) => ext.trim().toLowerCase())
+            .filter(Boolean)
+        : [];
+    const baseCandidates = process.platform === "win32" && extname(name) === ""
+        ? [name, ...pathExts.map((ext) => `${name}${ext}`)]
+        : [name];
+    if (isAbsolute(name) &&
+        baseCandidates.some((candidate) => existsSync(candidate))) {
+        return true;
+    }
+    const pathDirs = [
+        ...new Set([
+            (process.env.PATH ?? "").split(delimiter),
+            dirname(process.execPath),
+        ].flat()),
+    ].filter(Boolean);
+    for (const dir of pathDirs) {
+        for (const candidate of baseCandidates) {
+            if (existsSync(join(dir, candidate)))
+                return true;
+        }
+    }
+    return false;
+}
+function resolveConfigPath(config, pathStr) {
+    const parts = pathStr.split(".");
+    let current = config;
+    for (const part of parts) {
+        if (current === null ||
+            current === undefined ||
+            typeof current !== "object") {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+function isConfigPathTruthy(config, pathStr) {
+    const value = resolveConfigPath(config, pathStr);
+    return (value !== undefined &&
+        value !== null &&
+        value !== false &&
+        value !== "" &&
+        value !== 0);
+}
+export function checkEligibility(metadata, hookConfig, elizaConfig = {}) {
+    const missing = [];
+    if (!metadata) {
+        return { eligible: true, missing: [] };
+    }
+    // Note: hookConfig.enabled is intentionally NOT checked here.
+    // "Disabled" (user choice) vs "ineligible" (missing requirements) are
+    // separate concerns — the loader handles the enabled flag.
+    if (metadata.os && metadata.os.length > 0) {
+        if (!metadata.os.includes(platform())) {
+            missing.push(`OS: requires ${metadata.os.join("|")}, current: ${platform()}`);
+        }
+    }
+    if (metadata.always) {
+        return { eligible: missing.length === 0, missing };
+    }
+    if (metadata.requires?.bins) {
+        for (const bin of metadata.requires.bins) {
+            if (!binaryExists(bin)) {
+                missing.push(`Binary missing: ${bin}`);
+            }
+        }
+    }
+    if (metadata.requires?.anyBins && metadata.requires.anyBins.length > 0) {
+        const hasAny = metadata.requires.anyBins.some(binaryExists);
+        if (!hasAny) {
+            missing.push(`None of: ${metadata.requires.anyBins.join(", ")}`);
+        }
+    }
+    if (metadata.requires?.env) {
+        for (const envVar of metadata.requires.env) {
+            const hasInProcess = Boolean(process.env[envVar]);
+            const hasInHookConfig = Boolean(hookConfig?.env?.[envVar]);
+            if (!hasInProcess && !hasInHookConfig) {
+                missing.push(`Env missing: ${envVar}`);
+            }
+        }
+    }
+    if (metadata.requires?.config) {
+        for (const configPath of metadata.requires.config) {
+            if (!isConfigPathTruthy(elizaConfig, configPath)) {
+                missing.push(`Config missing: ${configPath}`);
+            }
+        }
+    }
+    return { eligible: missing.length === 0, missing };
+}
+export function resolveHookConfig(internalConfig, hookKey) {
+    return internalConfig?.entries?.[hookKey];
+}

package/dist/packages/agent/src/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export { type LoadHooksOptions, loadHooks, } from "./loader.ts";
+export { createHookEvent, triggerHook, } from "./registry.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/packages/agent/src/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,SAAS,GACV,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,WAAW,GACZ,MAAM,eAAe,CAAC"}

package/dist/packages/agent/src/hooks/index.js

@@ -0,0 +1,2 @@
+export { loadHooks, } from "./loader.js";
+export { createHookEvent, triggerHook, } from "./registry.js";