@elizaos/agent 2.0.0-beta.2 → 2.0.3-beta.3

package/runtime/conversation-compactor.types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared type contract for conversation-history compactors.
+ *
+ * Distinct from prompt-compaction.ts (presentation-layer regex stripping).
+ * A Compactor takes a multi-turn transcript and returns a smaller artifact
+ * that preserves the load-bearing facts, decisions, and tool-call/tool-result
+ * pairs needed for the agent to continue coherently.
+ *
+ * Mirrors the shape used by CompactBench
+ * (https://github.com/compactbench/compactbench) so our compactors can be
+ * benchmarked through that harness without per-method shims.
+ */
+export type CompactorRole = "system" | "developer" | "user" | "assistant" | "tool";
+export type CompactorToolCall = {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+};
+export type CompactorMessage = {
+    role: CompactorRole;
+    /** Plain text content. Multi-modal blocks are flattened to text upstream. */
+    content: string;
+    /** For assistant messages that invoke tools. */
+    toolCalls?: CompactorToolCall[];
+    /** For tool-role messages, the id of the assistant tool_call this answers. */
+    toolCallId?: string;
+    /** Tool name, mirrored on tool-role messages for readability/auditing. */
+    toolName?: string;
+    /** Optional epoch ms — used for time-aware summarization, not required. */
+    timestamp?: number;
+    /** Free-form tags propagated by the runtime (e.g. "thought", "observation"). */
+    tags?: string[];
+};
+export type CompactorTranscript = {
+    /** All messages in chronological order. The system prompt, if present, is index 0. */
+    messages: CompactorMessage[];
+    /** Free-form metadata (scenario id, agent name, intent, etc.). */
+    metadata?: Record<string, unknown>;
+};
+export type CompactionStats = {
+    originalMessageCount: number;
+    compactedMessageCount: number;
+    /** Approximate token counts using the configured counter. */
+    originalTokens: number;
+    compactedTokens: number;
+    /** Model id used for summarization, if the strategy called a model. */
+    summarizationModel?: string;
+    /** End-to-end wall time in ms. */
+    latencyMs: number;
+    /** Strategy-specific telemetry — never assume keys; for inspection only. */
+    extra?: Record<string, unknown>;
+};
+export type CompactionArtifact = {
+    /**
+     * Replacement messages for the compacted region. The runtime concatenates
+     * these in place of the messages that were summarized; tail messages
+     * (within `preserveTailMessages`) remain untouched.
+     */
+    replacementMessages: CompactorMessage[];
+    stats: CompactionStats;
+};
+/**
+ * Token counter callback. Implementations may use tiktoken, a model API,
+ * or a heuristic (4 chars per token). Must be deterministic for a given input.
+ */
+export type TokenCounter = (text: string) => number;
+/**
+ * Model invocation callback used by summarization-based compactors.
+ * Should return the raw text response. Errors propagate.
+ */
+export type CompactorModelCall = (params: {
+    systemPrompt: string;
+    messages: CompactorMessage[];
+    /** Hard cap on response tokens; implementations may ignore. */
+    maxOutputTokens?: number;
+}) => Promise<string>;
+export type CompactorOptions = {
+    /** Soft target token budget for the compacted artifact. */
+    targetTokens: number;
+    /**
+     * Number of trailing messages to preserve verbatim. Default 6.
+     * Tool-call/tool-result pairs that straddle this boundary are kept paired
+     * (the compactor may shift the boundary outward to avoid splitting a pair).
+     */
+    preserveTailMessages?: number;
+    /** Token counter; defaults to a 4-chars-per-token heuristic if omitted. */
+    countTokens?: TokenCounter;
+    /** Required for summarization-based strategies; optional for stripping ones. */
+    callModel?: CompactorModelCall;
+    /** Model id to record in stats — does not change `callModel` behavior. */
+    summarizationModel?: string;
+};
+export interface Compactor {
+    readonly name: string;
+    readonly version: string;
+    compact(transcript: CompactorTranscript, options: CompactorOptions): Promise<CompactionArtifact>;
+}
+/** 4-chars-per-token heuristic. Cheap, deterministic, model-agnostic. */
+export declare function approxCountTokens(text: string): number;
+/** Sum of approximate tokens across all message contents and tool args. */
+export declare function countTranscriptTokens(transcript: CompactorTranscript, counter?: TokenCounter): number;
+//# sourceMappingURL=conversation-compactor.types.d.ts.map

package/runtime/conversation-compactor.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-compactor.types.d.ts","sourceRoot":"","sources":["../../src/runtime/conversation-compactor.types.ts"],"names":[],"mappings":"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"}

package/runtime/core-plugins.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Core plugin package lists shared by runtime startup and the API server.
+ *
+ * Keeping this in a standalone module avoids a circular dependency between
+ * `api/server.ts` and `runtime/eliza.ts`.
+ */
+/**
+ * Plugins that depend on PTY/native workspace tooling.
+ * Keep them out of cloud images where those binaries are intentionally absent.
+ */
+export declare const DESKTOP_ONLY_PLUGINS: readonly string[];
+/**
+ * Mobile-safe core plugins. Used when `ELIZA_PLATFORM=android` (or `ios`).
+ *
+ * Phones cannot host the workflow runtime, the Signal CLI, the swarm orchestrator,
+ * the sandbox engine, the desktop launch hooks, or the autonomous PTY tools.
+ * They also have no `/usr/bin/open`, `osascript`, `xdg-open`, `ffmpeg`,
+ * `wmctrl`, etc., so plugins that bind to those at init crash the runtime.
+ *
+ * The mobile boot ships only `@elizaos/plugin-sql` (PGlite-backed memory
+ * store, required) plus AI provider plugins (`@elizaos/plugin-anthropic`,
+ * `@elizaos/plugin-openai`, `@elizaos/plugin-ollama`) which `collectPluginNames`
+ * adds based on the user's API keys. They are statically imported in the agent
+ * runtime so they bundle cleanly without filesystem-based plugin resolution.
+ *
+ * `@elizaos/plugin-local-inference` is intentionally excluded from the
+ * default mobile boot list: it pulls in the bun:ffi desktop dylib path plus
+ * a sizeable runtime (catalog, mtp subprocess client, voice pipeline)
+ * that the Capacitor WebView agent does not need. On mobile, embeddings
+ * come either from a cloud provider, the WebView-side llama-cpp-capacitor
+ * binding, or the AOSP-only FFI bridge
+ * (`@elizaos/plugin-aosp-local-inference`) when `ELIZA_LOCAL_LLAMA=1`.
+ */
+export declare const MOBILE_CORE_PLUGINS: readonly string[];
+/**
+ * View-providing plugins that must register their `/api/views` entries on EVERY
+ * platform — including stock mobile — so their home tiles resolve to a real
+ * destination instead of dead-ending in the apps catalog. These are bundled
+ * statically and either ship no backend or degrade gracefully without one (the
+ * heavy backends they pair with, e.g. agent-orchestrator, stay gated
+ * separately). Seeded into the load set for all platforms and spread into the
+ * mobile allow-list so the mobile filter keeps them.
+ */
+export declare const MOBILE_VIEW_PLUGINS: readonly string[];
+/**
+ * ElizaOS-only overlay app plugins. Used when the runtime is the custom
+ * Android OS build (`ELIZA_PLATFORM=android` plus `ELIZA_LOCAL_LLAMA=1`),
+ * appended to `MOBILE_CORE_PLUGINS` in `collectPluginNames`. Each one is a
+ * runtime-app plugin (the `/plugin` subpath of the matching overlay app)
+ * that exposes privileged system surfaces — WiFi, Contacts, Phone — to the
+ * agent as actions. The overlay UIs themselves register at app boot via
+ * `@elizaos/plugin-{wifi,contacts,phone}/register`, gated on `isElizaOS()` so
+ * stock Android, iOS, web, and desktop leave them inactive.
+ *
+ * Stock Android does not get these because Play Store style builds should not
+ * expose privileged OS-control surfaces merely because `Capacitor` reports
+ * `android`.
+ */
+export declare const ELIZAOS_ANDROID_CORE_PLUGINS: readonly string[];
+/**
+ * Terminal / shell / coding-tool plugins available on the privileged AOSP
+ * build only. The privileged Android service spawns bun under the priv_app
+ * SELinux context which permits `execve`, so shell, native file actions, and
+ * subprocess-backed coding-agent orchestration can work where they would not on
+ * stock Android.
+ *
+ * Stock Play-Store Android cannot have these — `execve` of arbitrary binaries
+ * is blocked by the default SELinux policy and would also fail Play review.
+ */
+export declare const ELIZAOS_ANDROID_TERMINAL_PLUGINS: readonly string[];
+/** Core plugins that should always be loaded. collectPluginNames() seeds from this list only. */
+export declare const CORE_PLUGINS: readonly string[];
+/**
+ * Minimal plugin set for a dedicated, chat-only cloud agent (#8434). A dedicated
+ * agent boots a full local AgentRuntime inside its container; the default
+ * CORE_PLUGINS set carries heavy coding/automation surfaces (shell, coding-tools,
+ * browser, the orchestrator, gitpathologist) that a purely conversational agent
+ * never uses and that dominate its cold-boot time. Opt in per agent by setting
+ * `ELIZA_PLUGIN_SET=lean-chat` in the container environment.
+ *
+ * Browser is intentionally excluded — it stays OFF for lean chat until the
+ * browser surface is production-ready. This set is for dedicated agents only;
+ * cloud-PROXIED (shared-runtime) agents boot zero plugins by construction.
+ */
+export declare const LEAN_CHAT_PLUGINS: readonly string[];
+/**
+ * Heavy surfaces force-excluded under `ELIZA_PLUGIN_SET=lean-chat` even when some
+ * other gate would otherwise add them (ELIZA_AGENT_ORCHESTRATOR, gitpathologist
+ * .git auto-detect, config allow-lists). Guarantees a lean chat agent stays lean.
+ * Browser is listed per the "browser disabled until ready" decision.
+ */
+export declare const LEAN_CHAT_EXCLUDED_PLUGINS: readonly string[];
+/**
+ * Core plugins that must be imported and registered before the runtime can be
+ * considered ready. Keep this list intentionally small: everything else in
+ * CORE_PLUGINS should load in the deferred phase so slow feature/provider
+ * imports do not block API readiness.
+ */
+export declare const BLOCKING_CORE_PLUGINS: readonly string[];
+/**
+ * Core plugins loaded after runtime readiness. Dependency ordering is handled
+ * by preregisterCorePluginsInDependencyWaves() in eliza.ts.
+ *
+ * These are imported in the BACKGROUND after `ready:true` (runDeferredBoot in
+ * eliza.ts). They are NOT candidates for further first-use lazy loading: every
+ * one registers a provider (so the planner prompt knows the capability exists),
+ * an action the model must be able to select, or a service/event listener with
+ * a boot-time obligation. Deferring any of them behind a stub that imports on
+ * first invocation would silently strip the capability from the planner's
+ * awareness — the model cannot ask for an action or read a provider that has
+ * not registered yet. Concretely, in this set:
+ *   - companion       — PLAY_EMOTE action + VRM views
+ *   - app-control     — app launch/close/list actions
+ *   - shell           — shell service + shell-history provider
+ *   - coding-tools    — FILE/SHELL/WORKTREE actions + available-tools provider
+ *   - agent-skills    — USE_SKILL action + enabled-skills provider
+ *   - commands        — slash-command provider + command registry
+ *   - browser         — browser actions + bridge routes
+ * The genuinely on-demand connector/feature plugins that have NO boot
+ * obligation (e.g. plugin-video — service-only, reached via getService(VIDEO);
+ * and the orchestrator's task-coordinator companion — views-only metadata) are
+ * not in this core set: they enter via plugin-collector only when configured,
+ * and their boot cost is resolver/staging overhead, not module-body evaluation
+ * that a lazy import could avoid (their server modules import only `type`-level
+ * symbols). The heaviest deferred imports measured (agent-orchestrator,
+ * shell, coding-tools, commands) all register providers/actions or eager-start
+ * event-subscribing services and therefore must stay at boot. See
+ * benchmarks/loadperf/research/03-agent-boot-plugins.md.
+ *
+ * Cloud-hosted topology (deploymentTarget.runtime === "cloud") never reaches
+ * this set: startEliza() returns startInCloudMode() before the deferred-boot
+ * machinery is even defined, so a cloud-proxied agent loads ZERO deferred
+ * plugins by construction (no local AgentRuntime boots) — the device-local
+ * plugins above are skipped wholesale in that topology with no extra gating.
+ */
+export declare const DEFERRED_CORE_PLUGINS: readonly string[];
+/**
+ * Plugins that can be enabled from the admin panel.
+ * Not loaded by default — require explicit configuration or have platform dependencies.
+ */
+export declare const OPTIONAL_CORE_PLUGINS: readonly string[];
+//# sourceMappingURL=core-plugins.d.ts.map

package/runtime/core-plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-plugins.d.ts","sourceRoot":"","sources":["../../src/runtime/core-plugins.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAGjD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAahD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAahD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,MAAM,EAIzD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,MAAM,EAI7D,CAAC;AAEF,iGAAiG;AACjG,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAqBzC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAQ9C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EA4BvD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAGlD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAElD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EA4BlD,CAAC"}

package/runtime/core-plugins.js

@@ -0,0 +1,266 @@
+/**
+ * Core plugin package lists shared by runtime startup and the API server.
+ *
+ * Keeping this in a standalone module avoids a circular dependency between
+ * `api/server.ts` and `runtime/eliza.ts`.
+ */
+/**
+ * Plugins that depend on PTY/native workspace tooling.
+ * Keep them out of cloud images where those binaries are intentionally absent.
+ */
+export const DESKTOP_ONLY_PLUGINS = [
+    "agent-orchestrator",
+    "coding-tools",
+];
+/**
+ * Mobile-safe core plugins. Used when `ELIZA_PLATFORM=android` (or `ios`).
+ *
+ * Phones cannot host the workflow runtime, the Signal CLI, the swarm orchestrator,
+ * the sandbox engine, the desktop launch hooks, or the autonomous PTY tools.
+ * They also have no `/usr/bin/open`, `osascript`, `xdg-open`, `ffmpeg`,
+ * `wmctrl`, etc., so plugins that bind to those at init crash the runtime.
+ *
+ * The mobile boot ships only `@elizaos/plugin-sql` (PGlite-backed memory
+ * store, required) plus AI provider plugins (`@elizaos/plugin-anthropic`,
+ * `@elizaos/plugin-openai`, `@elizaos/plugin-ollama`) which `collectPluginNames`
+ * adds based on the user's API keys. They are statically imported in the agent
+ * runtime so they bundle cleanly without filesystem-based plugin resolution.
+ *
+ * `@elizaos/plugin-local-inference` is intentionally excluded from the
+ * default mobile boot list: it pulls in the bun:ffi desktop dylib path plus
+ * a sizeable runtime (catalog, mtp subprocess client, voice pipeline)
+ * that the Capacitor WebView agent does not need. On mobile, embeddings
+ * come either from a cloud provider, the WebView-side llama-cpp-capacitor
+ * binding, or the AOSP-only FFI bridge
+ * (`@elizaos/plugin-aosp-local-inference`) when `ELIZA_LOCAL_LLAMA=1`.
+ */
+export const MOBILE_CORE_PLUGINS = [
+    "@elizaos/plugin-sql",
+    "@elizaos/plugin-background-runner",
+    "@elizaos/plugin-device-filesystem",
+    // Screen understanding on mobile (EPIC #9105): the GET_SCREEN op + the
+    // renderer-pulled screen-capture bridge + the IMAGE_DESCRIPTION describe
+    // path. plugin-vision is now mobile-safe — `sharp` is lazy-loaded with a
+    // pure-JS fallback and the native YOLO/face detectors are dynamic-imported,
+    // so module-eval no longer pulls a native addon. VisionService degrades
+    // gracefully on a phone (camera mode finds no capture tool → warns, never
+    // starts a processing loop), and its computeruse OCR/set-of-marks bridges
+    // are best-effort dynamic imports that no-op without plugin-computeruse.
+    "@elizaos/plugin-vision",
+];
+/**
+ * View-providing plugins that must register their `/api/views` entries on EVERY
+ * platform — including stock mobile — so their home tiles resolve to a real
+ * destination instead of dead-ending in the apps catalog. These are bundled
+ * statically and either ship no backend or degrade gracefully without one (the
+ * heavy backends they pair with, e.g. agent-orchestrator, stay gated
+ * separately). Seeded into the load set for all platforms and spread into the
+ * mobile allow-list so the mobile filter keeps them.
+ */
+export const MOBILE_VIEW_PLUGINS = [
+    "@elizaos/plugin-task-coordinator",
+    // Inbox: registered on mobile so its home tile resolves + the /inbox view
+    // appears in /api/views. The plugin's de-stub + client wiring are owned by a
+    // separate effort; this keeps it in the mobile load/allow set.
+    "@elizaos/plugin-inbox",
+    // App-control: provides the VIEWS navigation action + the contextual
+    // view-switch evaluators. Without it, mobile chat has no way to act on
+    // "open settings" / "go to my calendar" — view switching only worked on
+    // desktop/web. Its view-nav path (VIEWS action, evaluators, available-apps
+    // provider) needs no services; the app-launch/verification/worker-host
+    // services it also registers stay idle on mobile (no registered apps).
+    "@elizaos/plugin-app-control",
+];
+/**
+ * ElizaOS-only overlay app plugins. Used when the runtime is the custom
+ * Android OS build (`ELIZA_PLATFORM=android` plus `ELIZA_LOCAL_LLAMA=1`),
+ * appended to `MOBILE_CORE_PLUGINS` in `collectPluginNames`. Each one is a
+ * runtime-app plugin (the `/plugin` subpath of the matching overlay app)
+ * that exposes privileged system surfaces — WiFi, Contacts, Phone — to the
+ * agent as actions. The overlay UIs themselves register at app boot via
+ * `@elizaos/plugin-{wifi,contacts,phone}/register`, gated on `isElizaOS()` so
+ * stock Android, iOS, web, and desktop leave them inactive.
+ *
+ * Stock Android does not get these because Play Store style builds should not
+ * expose privileged OS-control surfaces merely because `Capacitor` reports
+ * `android`.
+ */
+export const ELIZAOS_ANDROID_CORE_PLUGINS = [
+    "@elizaos/plugin-wifi",
+    "@elizaos/plugin-contacts",
+    "@elizaos/plugin-phone",
+];
+/**
+ * Terminal / shell / coding-tool plugins available on the privileged AOSP
+ * build only. The privileged Android service spawns bun under the priv_app
+ * SELinux context which permits `execve`, so shell, native file actions, and
+ * subprocess-backed coding-agent orchestration can work where they would not on
+ * stock Android.
+ *
+ * Stock Play-Store Android cannot have these — `execve` of arbitrary binaries
+ * is blocked by the default SELinux policy and would also fail Play review.
+ */
+export const ELIZAOS_ANDROID_TERMINAL_PLUGINS = [
+    "@elizaos/plugin-shell",
+    "@elizaos/plugin-coding-tools",
+    "agent-orchestrator",
+];
+/** Core plugins that should always be loaded. collectPluginNames() seeds from this list only. */
+export const CORE_PLUGINS = [
+    "@elizaos/plugin-sql", // database adapter — required
+    "@elizaos/plugin-local-inference", // local Eliza-1 inference (text + embeddings + voice) — required for memory + on-device generation
+    // @elizaos/plugin-form — standalone form plugin; load via plugin registry/config
+    "@elizaos/plugin-companion", // VRM companion emotes; actions gated until app session is active
+    // @elizaos/plugin-agent-orchestrator — opt-in via ELIZA_AGENT_ORCHESTRATOR (Eliza app enables by default)
+    // Recurring work uses runtime TaskService + triggers (no @elizaos/plugin-cron).
+    "@elizaos/plugin-app-control", // launch, close, and list running Eliza apps from agent chat
+    "@elizaos/plugin-device-filesystem", // mobile-safe FILE target=device via Capacitor on iOS/Android, Node fs/promises rooted under resolveStateDir()/workspace on desktop/AOSP
+    "@elizaos/plugin-shell", // shell service, approvals, and history provider
+    "@elizaos/plugin-coding-tools", // native FILE/SHELL/WORKTREE coding tools (desktop-only
+    "@elizaos/plugin-agent-skills", // skill execution and marketplace runtime
+    "@elizaos/plugin-commands", // slash command handling (skills auto-register as /commands)
+    "@elizaos/plugin-browser", // Browser workspace and Chrome/Safari companion bridge.
+    // Built-in runtime capabilities (no longer external plugins):
+    // - experience, todos, personality: advanced capabilities (advancedCapabilities: true)
+    // - form: standalone @elizaos/plugin-form
+    // - trust: core capability (enableTrust: true)
+    // - secrets (SECRETS): core capability (enableSecretsManager: true)
+    // - plugin-manager: core capability (enablePluginManager: true)
+    // - knowledge, relationships, trajectories: native features
+];
+/**
+ * Minimal plugin set for a dedicated, chat-only cloud agent (#8434). A dedicated
+ * agent boots a full local AgentRuntime inside its container; the default
+ * CORE_PLUGINS set carries heavy coding/automation surfaces (shell, coding-tools,
+ * browser, the orchestrator, gitpathologist) that a purely conversational agent
+ * never uses and that dominate its cold-boot time. Opt in per agent by setting
+ * `ELIZA_PLUGIN_SET=lean-chat` in the container environment.
+ *
+ * Browser is intentionally excluded — it stays OFF for lean chat until the
+ * browser surface is production-ready. This set is for dedicated agents only;
+ * cloud-PROXIED (shared-runtime) agents boot zero plugins by construction.
+ */
+export const LEAN_CHAT_PLUGINS = [
+    "@elizaos/plugin-sql", // database adapter — required
+    "@elizaos/plugin-local-inference", // text + embeddings + voice — required for memory + generation
+    "@elizaos/plugin-companion", // VRM companion emotes for the app chat surface
+    "@elizaos/plugin-app-control", // VIEWS navigation in the app chat surface
+    "@elizaos/plugin-device-filesystem", // mobile-safe FILE target
+    "@elizaos/plugin-agent-skills", // skill execution + enabled-skills provider
+    "@elizaos/plugin-commands", // slash commands
+];
+/**
+ * Heavy surfaces force-excluded under `ELIZA_PLUGIN_SET=lean-chat` even when some
+ * other gate would otherwise add them (ELIZA_AGENT_ORCHESTRATOR, gitpathologist
+ * .git auto-detect, config allow-lists). Guarantees a lean chat agent stays lean.
+ * Browser is listed per the "browser disabled until ready" decision.
+ */
+export const LEAN_CHAT_EXCLUDED_PLUGINS = [
+    "@elizaos/plugin-shell",
+    "@elizaos/plugin-coding-tools",
+    "@elizaos/plugin-browser",
+    "agent-orchestrator",
+    "@elizaos/plugin-agent-orchestrator",
+    "@elizaos/plugin-gitpathologist",
+    // Cloud chat agents route models to Eliza Cloud (plugin-elizacloud), which
+    // serves TEXT_EMBEDDING via the fast 1536-dim cloud endpoint. plugin-local-
+    // inference otherwise wins the TEXT_EMBEDDING registration with an on-device
+    // gte-small GGUF that runs on the container's (contended) CPU — measured at
+    // 1.5–98s per batch and ~30s/turn on a dedicated agent, plus a 384↔1536
+    // dimension mismatch that drops every memory insert. A cloud agent has no
+    // local GPU and no reason to run local inference, so exclude it and let the
+    // cloud embedding handler serve TEXT_EMBEDDING.
+    "@elizaos/plugin-local-inference",
+    // Cloud agent containers are Steward-provisioned (ELIZA_CLOUD_PROVISIONED=1 +
+    // STEWARD_API_URL + STEWARD_AGENT_TOKEN), which trips plugin-wallet's
+    // auto-enable manifest (hasCloudStewardWallet) on EVERY agent — even a purely
+    // conversational one. Its evmWalletProvider then warms on-chain balances at
+    // boot (getBalance(mainnet)+getBalance(base)), each a 3s RPC that times out
+    // against the cloud RPC and falls back to a public node — ~6s of dead boot
+    // time and recurring RPC noise for an agent that never reads a balance.
+    // plugin-workflow auto-enables for the same structural reason with no chat
+    // value. Auto-enable runs before the lean-chat force-drop (plugin-collector),
+    // so listing them here is what actually keeps them out of a lean chat agent.
+    "@elizaos/plugin-wallet",
+    "@elizaos/plugin-workflow",
+];
+/**
+ * Core plugins that must be imported and registered before the runtime can be
+ * considered ready. Keep this list intentionally small: everything else in
+ * CORE_PLUGINS should load in the deferred phase so slow feature/provider
+ * imports do not block API readiness.
+ */
+export const BLOCKING_CORE_PLUGINS = [
+    "@elizaos/plugin-sql", // required database adapter
+    "@elizaos/plugin-local-inference", // pre-init local model/embedding handler wiring
+];
+/**
+ * Core plugins loaded after runtime readiness. Dependency ordering is handled
+ * by preregisterCorePluginsInDependencyWaves() in eliza.ts.
+ *
+ * These are imported in the BACKGROUND after `ready:true` (runDeferredBoot in
+ * eliza.ts). They are NOT candidates for further first-use lazy loading: every
+ * one registers a provider (so the planner prompt knows the capability exists),
+ * an action the model must be able to select, or a service/event listener with
+ * a boot-time obligation. Deferring any of them behind a stub that imports on
+ * first invocation would silently strip the capability from the planner's
+ * awareness — the model cannot ask for an action or read a provider that has
+ * not registered yet. Concretely, in this set:
+ *   - companion       — PLAY_EMOTE action + VRM views
+ *   - app-control     — app launch/close/list actions
+ *   - shell           — shell service + shell-history provider
+ *   - coding-tools    — FILE/SHELL/WORKTREE actions + available-tools provider
+ *   - agent-skills    — USE_SKILL action + enabled-skills provider
+ *   - commands        — slash-command provider + command registry
+ *   - browser         — browser actions + bridge routes
+ * The genuinely on-demand connector/feature plugins that have NO boot
+ * obligation (e.g. plugin-video — service-only, reached via getService(VIDEO);
+ * and the orchestrator's task-coordinator companion — views-only metadata) are
+ * not in this core set: they enter via plugin-collector only when configured,
+ * and their boot cost is resolver/staging overhead, not module-body evaluation
+ * that a lazy import could avoid (their server modules import only `type`-level
+ * symbols). The heaviest deferred imports measured (agent-orchestrator,
+ * shell, coding-tools, commands) all register providers/actions or eager-start
+ * event-subscribing services and therefore must stay at boot. See
+ * benchmarks/loadperf/research/03-agent-boot-plugins.md.
+ *
+ * Cloud-hosted topology (deploymentTarget.runtime === "cloud") never reaches
+ * this set: startEliza() returns startInCloudMode() before the deferred-boot
+ * machinery is even defined, so a cloud-proxied agent loads ZERO deferred
+ * plugins by construction (no local AgentRuntime boots) — the device-local
+ * plugins above are skipped wholesale in that topology with no extra gating.
+ */
+export const DEFERRED_CORE_PLUGINS = CORE_PLUGINS.filter((pluginName) => !BLOCKING_CORE_PLUGINS.includes(pluginName));
+/**
+ * Plugins that can be enabled from the admin panel.
+ * Not loaded by default — require explicit configuration or have platform dependencies.
+ */
+export const OPTIONAL_CORE_PLUGINS = [
+    // plugin-manager, secrets (SECRETS), trust: now built-in core capabilities
+    // Enable via character settings: ENABLE_PLUGIN_MANAGER, ENABLE_SECRETS_MANAGER, ENABLE_TRUST
+    "@elizaos/plugin-google", // Google Workspace connector (requires googleapis + explicit OAuth config); only loaded when LifeOps/Google is enabled
+    "@elizaos/plugin-personal-assistant", // LifeOps: personal ops - tasks, goals, calendar, inbox, website blocking (requires @capacitor/core + plugin-google); enable explicitly
+    "@elizaos/plugin-finances", // Owner finances dashboard (app_finances schema); auto-registered by plugin-personal-assistant, also enablable standalone
+    "@elizaos/plugin-pdf", // PDF processing (published bundle broken in alpha.15)
+    "@elizaos/plugin-cua", // CUA computer-use agent (cloud sandbox automation)
+    "@elizaos/plugin-obsidian", // Obsidian vault CLI integration
+    "@elizaos/plugin-repoprompt", // RepoPrompt CLI integration and workflow orchestration
+    "@elizaos/plugin-computeruse", // computer use automation (requires platform-specific binaries)
+    "@elizaos/plugin-browser", // browser automation (app/bridge first, optional stagehand fallback)
+    "@elizaos/plugin-vision", // vision/image understanding (feature-gated)
+    "@elizaos/plugin-cli", // CLI interface
+    "@elizaos/plugin-discord", // Discord bot integration
+    "@elizaos/plugin-discord-local", // Local Discord desktop integration for macOS
+    "@elizaos/plugin-bluebubbles", // BlueBubbles-backed iMessage integration for macOS
+    "@elizaos/plugin-telegram", // Telegram bot integration
+    "@elizaos/plugin-signal", // Signal user-account integration
+    "@elizaos/plugin-twitch", // Twitch integration
+    "@elizaos/plugin-edge-tts", // text-to-speech (Microsoft Edge TTS)
+    "@elizaos/plugin-elevenlabs", // ElevenLabs text-to-speech
+    "@elizaos/plugin-music", // Library, playback, and streaming routes.
+    "@elizaos/plugin-gitpathologist", // forensic git-history analysis (opt-in via ELIZA_GITPATHOLOGIST, auto-on when .git/ exists)
+    // "@elizaos/plugin-directives", // directive processing remains opt-in
+    // "@elizaos/plugin-mcp", // MCP protocol support remains opt-in
+    // "@elizaos/plugin-scheduling", // scheduling remains opt-in
+    // todos: now built-in as advanced capability (advancedCapabilities: true)
+];

package/runtime/custom-actions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Custom Actions runtime loader.
+ *
+ * Converts `CustomActionDef[]` from config into elizaOS `Action[]` objects
+ * so the agent can use them in conversations.
+ *
+ * @module runtime/custom-actions
+ */
+import { type Action, type IAgentRuntime } from "@elizaos/core";
+import type { CustomActionDef } from "../config/types.eliza.js";
+/**
+ * Store the runtime reference so we can hot-register actions later.
+ * Called once from plugin.init().
+ */
+export declare function setCustomActionsRuntime(runtime: IAgentRuntime): void;
+/**
+ * Hot-register a CustomActionDef into the running agent.
+ * Returns the elizaOS Action that was registered, or null if no runtime.
+ */
+export declare function registerCustomActionLive(def: CustomActionDef): Action | null;
+export declare class CustomActionTimeoutError extends Error {
+    constructor(message: string);
+}
+type ResolvedUrlTarget = {
+    parsed: URL;
+    hostname: string;
+    pinnedAddress: string;
+};
+type PinnedFetchInput = {
+    url: URL;
+    init: RequestInit;
+    target: ResolvedUrlTarget;
+    timeoutMs: number;
+};
+type PinnedFetchImpl = (input: PinnedFetchInput) => Promise<Response>;
+type DnsLookupRecord = {
+    address?: unknown;
+} | string;
+type DnsLookupAllFn = (hostname: string, options: {
+    all: true;
+}) => Promise<DnsLookupRecord[] | DnsLookupRecord>;
+export declare function __setPinnedFetchImplForTests(impl: PinnedFetchImpl | null): void;
+export declare function __setDnsLookupImplForTests(impl: DnsLookupAllFn | null): void;
+export interface GuardedHttpGetOptions {
+    /** Request timeout in milliseconds. Defaults to the custom-action cap. */
+    timeoutMs?: number;
+    /** Maximum number of body characters to read. Defaults to {@link GUARDED_GET_MAX_BYTES}. */
+    maxChars?: number;
+    /** Optional extra request headers (e.g. Accept). */
+    headers?: Record<string, string>;
+}
+export interface GuardedHttpGetResult {
+    /** True when the host passed the SSRF guard and the request completed. */
+    ok: boolean;
+    /** HTTP status code, or 0 when the request was blocked before sending. */
+    status: number;
+    /** Truncated response body text (empty when blocked). */
+    text: string;
+    /** True when the URL was rejected by the SSRF / scheme guard. */
+    blocked: boolean;
+}
+export interface GuardedHttpPostOptions extends GuardedHttpGetOptions {
+    /** Request body. Sent as `application/json` unless `Content-Type` is set. */
+    body: string;
+}
+/** SSRF-guarded https-only GET (custom actions + the built-in WEB_FETCH action). */
+export declare function performGuardedHttpGet(url: string, opts?: GuardedHttpGetOptions): Promise<GuardedHttpGetResult>;
+/**
+ * SSRF-guarded HTTPS POST with a body (default `application/json`) — used by
+ * inline actions that call a public JSON/MCP endpoint (e.g. the keyless
+ * web-search MCP). Same guard as {@link performGuardedHttpGet}.
+ */
+export declare function performGuardedHttpPost(url: string, opts: GuardedHttpPostOptions): Promise<GuardedHttpGetResult>;
+export declare function loadCustomActions(): Action[];
+export declare function buildTestHandler(def: CustomActionDef): (params: Record<string, string>) => Promise<{
+    ok: boolean;
+    output: string;
+}>;
+export {};
+//# sourceMappingURL=custom-actions.d.ts.map

package/runtime/custom-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-actions.d.ts","sourceRoot":"","sources":["../../src/runtime/custom-actions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,OAAO,EACL,KAAK,MAAM,EAEX,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAIvB,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,0BAA0B,CAAC;AASlC;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAEpE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAK5E;AA2BD,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,KAAK,iBAAiB,GAAG;IACvB,MAAM,EAAE,GAAG,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,KAAK,gBAAgB,GAAG;IACtB,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,KAAK,eAAe,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AACtE,KAAK,eAAe,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAAC;AACtD,KAAK,cAAc,GAAG,CACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,KACnB,OAAO,CAAC,eAAe,EAAE,GAAG,eAAe,CAAC,CAAC;AAgTlD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,eAAe,GAAG,IAAI,GAC3B,IAAI,CAEN;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAE5E;AAmKD,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,EAAE,EAAE,OAAO,CAAC;IACZ,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB;AAgBD,MAAM,WAAW,sBAAuB,SAAQ,qBAAqB;IACnE,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;CACd;AAmED,oFAAoF;AACpF,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAkMD,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAa5C;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,eAAe,GACnB,CACD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC3B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAE5C"}