@elizaos/ui 2.0.0-alpha.534 → 2.0.0-alpha.537

package/packages/agent/src/runtime/eliza.js

@@ -25,7 +25,7 @@ import { resolvePlugins } from "./plugin-resolver.js";
 import { CUSTOM_PLUGINS_DIRNAME as CUSTOM_RUNTIME_PLUGINS_DIRNAME, STATIC_ELIZA_PLUGINS, } from "./plugin-types.js";
 export { CHANNEL_PLUGIN_MAP, collectPluginNames, OPTIONAL_PLUGIN_MAP, PROVIDER_PLUGIN_MAP, } from "./plugin-collector.js";
 import { applyAdvancedCapabilitySettings, resolveAdvancedCapabilitiesEnabled, } from "./advanced-capabilities-config.js";
-export { CUSTOM_PLUGINS_DIRNAME, EJECTED_PLUGINS_DIRNAME, ensureBrowserServerLink, findPluginBrowserStagehandDir, findRuntimePluginExport, mergeDropInPlugins, repairBrokenInstallRecord, resolveElizaPluginImportSpecifier, resolvePackageEntry, STATIC_ELIZA_PLUGINS, scanDropInPlugins, shouldIgnoreMissingPluginExport, } from "./plugin-types.js";
+export { CUSTOM_PLUGINS_DIRNAME, EJECTED_PLUGINS_DIRNAME, ensureBrowserServerLink, findPluginBrowserStagehandDir, findRuntimePluginExport, mergeDropInPlugins, repairBrokenInstallRecord, resolveElizaPluginImportSpecifier, resolvePackageEntry, STATIC_ELIZA_PLUGINS, scanDropInPlugins, } from "./plugin-types.js";
 // resolvePlugins is re-exported via index.ts from ./plugin-resolver
 // `@elizaos/app-lifeops` and `@elizaos/app-companion` are NOT eagerly imported
 // here. Both packages transitively import from `@elizaos/agent` (e.g.
@@ -47,7 +47,7 @@ import * as pluginAgentSkills from "@elizaos/plugin-agent-skills";
 import * as pluginBrowserBridge from "@elizaos/plugin-browser-bridge";
 import * as pluginPdf from "@elizaos/plugin-pdf";
 import * as pluginSql from "@elizaos/plugin-sql";
-import { formatError, getDefaultStylePreset, getOnboardingProviderOption, isElizaSettingsDebugEnabled, migrateLegacyRuntimeConfig, normalizeCharacterLanguage, normalizeOnboardingProviderId, resolveDeploymentTargetInConfig, resolveElizaCloudTopology, resolveServerOnlyPort, resolveServiceRoutingInConfig, resolveStylePresetByAvatarIndex, resolveStylePresetById, resolveStylePresetByName, settingsDebugCloudSummary, } from "@elizaos/shared";
+import { formatError, getDefaultStylePreset, getOnboardingProviderOption, isElizaSettingsDebugEnabled, isMobilePlatform, migrateLegacyRuntimeConfig, normalizeCharacterLanguage, normalizeOnboardingProviderId, resolveDeploymentTargetInConfig, resolveElizaCloudTopology, resolveServerOnlyPort, resolveServiceRoutingInConfig, resolveStylePresetByAvatarIndex, resolveStylePresetById, resolveStylePresetByName, settingsDebugCloudSummary, } from "@elizaos/shared";
 import { debugLogResolvedContext, validateRuntimeContext, } from "../api/plugin-validation.js";
 import { getWalletAddresses, syncSolanaPublicKeyEnv } from "../api/wallet.js";
 import { configFileExists, loadElizaConfig, } from "../config/config.js";
@@ -108,12 +108,16 @@ try {
 catch {
     pluginCommands = null;
 }
-let pluginCron = null;
+// Keep plugin-video behind a guarded runtime require. plugin-video's main
+// points at dist/index.js, which is not built in test/CI flows that do not
+// run a full plugin build first; a static ESM import then crashes vitest at
+// resolution time. Same pattern as plugin-shell / plugin-commands above.
+let pluginVideo = null;
 try {
-    pluginCron = require("@elizaos/plugin-cron");
+    pluginVideo = require("@elizaos/plugin-video");
 }
 catch {
-    pluginCron = null;
+    pluginVideo = null;
 }
 // Keep plugin-elizacloud behind a guarded runtime require as well. Some
 // published alpha builds advertise dist/node/index.node.js but do not ship
@@ -230,12 +234,12 @@ Object.assign(STATIC_ELIZA_PLUGINS, {
     ...(pluginAgentOrchestrator
         ? { "agent-orchestrator": pluginAgentOrchestrator }
         : {}),
-    ...(pluginCron ? { "@elizaos/plugin-cron": pluginCron } : {}),
     ...(pluginShell ? { "@elizaos/plugin-shell": pluginShell } : {}),
     // plugin-manager: now built-in core capability (ENABLE_PLUGIN_MANAGER)
     "@elizaos/plugin-agent-skills": pluginAgentSkills,
     ...(pluginCommands ? { "@elizaos/plugin-commands": pluginCommands } : {}),
     "@elizaos/plugin-pdf": pluginPdf,
+    ...(pluginVideo ? { "@elizaos/plugin-video": pluginVideo } : {}),
     ...(pluginOpenai ? { "@elizaos/plugin-openai": pluginOpenai } : {}),
     ...(pluginAnthropic ? { "@elizaos/plugin-anthropic": pluginAnthropic } : {}),
     ...(pluginOllama ? { "@elizaos/plugin-ollama": pluginOllama } : {}),
@@ -1152,49 +1156,72 @@ export function applyX402ConfigToEnv(config) {
 /**
  * Resolve N8N_HOST + N8N_API_KEY for @elizaos/plugin-n8n-workflow.
  *
- * Precedence:
- *   1. Existing process.env values (user override) — respected as-is.
- *   2. Eliza Cloud authenticated (cloud.apiKey present AND cloud.enabled !== false):
- *      N8N_HOST = `${cloudBaseUrl}/api/v1/agents/${agentId}/n8n`
- *      N8N_API_KEY = cloud.apiKey
- *   3. Local sidecar — the sidecar lifecycle writes `config.n8n.host` and
- *      `config.n8n.apiKey` when it reaches "ready". We pump those into
- *      process.env here when cloud did not fire. The authoritative shape is
- *      `N8nConfig` in types.eliza.ts.
- *   4. Otherwise: leave unset. The plugin's init() no-ops without credentials.
+ * Resolution order (first match wins, later sources are not consulted):
  *
- * Called from startEliza() after applyCloudConfigToEnv so cloud settings are
- * already reflected in process.env.
+ *   1. Explicit process.env (user override) — both N8N_HOST and N8N_API_KEY
+ *      already set. Respected as-is.
+ *
+ *   2. Eliza Cloud minted token. When `cloud.apiKey` is set and
+ *      `cloud.enabled !== false`, mint a short-lived scoped n8n token via
+ *      `POST {cloudBaseUrl}/api/v1/n8n/tokens` (auth: `Bearer <cloud.apiKey>`,
+ *      body: `{ purpose: "milady-runtime" }`). The full Cloud key is NEVER
+ *      passed through as `N8N_API_KEY`. The minted token is cached at
+ *      `<stateDir>/n8n/cloud-token.json` and reused while it has more than
+ *      60s of life remaining. See `docs/cloud/n8n-gateway-contract.md` (§4).
+ *
+ *      404 from the gateway endpoint → fall through to (3).
+ *      401/403 from the gateway → log error, fall through to (3).
+ *      Network/timeout → retried once, then fall through to (3).
+ *
+ *   3. Local sidecar. When not on a mobile platform, boot the local n8n
+ *      sidecar via the app-core sidecar bridge and await readiness. The
+ *      sidecar handles owner-setup → login → api-key minting itself; we
+ *      just wait for it to land in `ready` and surface its host + apiKey.
+ *      Mobile platforms skip this entirely (no child_process available).
+ *
+ *   4. Disabled. Leave env unset. The plugin's init() warns and the actions
+ *      return a structured error to the caller.
+ *
+ * Called from startEliza() after applyCloudConfigToEnv so cloud settings
+ * are already reflected in process.env.
  *
  * @internal Exported for testing.
  */
-export function applyN8nConfigToEnv(config, agentId) {
-    // 1. Respect existing process.env overrides.
+export async function applyN8nConfigToEnv(config, _agentId) {
+    // 1. Respect existing process.env overrides — the power-user path
+    //    (their own n8n on their own VPS).
     if (process.env.N8N_HOST && process.env.N8N_API_KEY)
         return;
     // Master gate — when config.n8n.enabled is false, do not pump anything.
     if (config.n8n?.enabled === false)
         return;
+    // 2. Eliza Cloud minted token.
     const cloud = config.cloud;
     const cloudAuthed = Boolean(cloud?.apiKey) && cloud?.enabled !== false;
     if (cloudAuthed && cloud?.apiKey) {
-        const rawBase = cloud.baseUrl ?? "https://www.elizacloud.ai";
-        // Strip trailing /api/v1 (or /api/v1/) plus any trailing slashes so we can
-        // build `${siteUrl}/api/v1/agents/${agentId}/n8n` without duplication.
-        const safeBase = rawBase.length > 8192 ? rawBase.slice(0, 8192) : rawBase;
-        const siteUrl = safeBase
-            .replace(/\/api\/v1\/?$/, "")
-            .replace(/\/{1,1024}$/, "");
-        const gateway = `${siteUrl}/api/v1/agents/${agentId}/n8n`;
-        if (!process.env.N8N_HOST)
-            process.env.N8N_HOST = gateway;
-        if (!process.env.N8N_API_KEY)
-            process.env.N8N_API_KEY = cloud.apiKey;
-        return;
+        try {
+            const { resolveN8nCloudToken } = await import("./n8n-cloud-resolver.js");
+            const stateDir = resolveStateDir();
+            const resolved = await resolveN8nCloudToken(cloud.apiKey, cloud.baseUrl ?? "https://www.elizacloud.ai", stateDir);
+            if (resolved) {
+                if (!process.env.N8N_HOST)
+                    process.env.N8N_HOST = resolved.host;
+                if (!process.env.N8N_API_KEY) {
+                    process.env.N8N_API_KEY = resolved.apiKey;
+                }
+                return;
+            }
+        }
+        catch (err) {
+            logger.warn(`[N8nCloudResolver] resolver crashed, falling through to sidecar: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Cloud failed but is configured — fall through to local sidecar
+        // (the autostart bridge will own ongoing lifecycle; we boot here only
+        // to populate env before the n8n plugin reads it).
     }
-    // 2. Local sidecar path — the sidecar populates `config.n8n.host` and
-    //    `config.n8n.apiKey` (authoritative N8nConfig shape) when it reaches
-    //    "ready". Surface those to process.env for the plugin.
+    // 2b. If the autostart bridge already populated config.n8n.host/apiKey
+    //     (e.g. on a hot-reload after the sidecar has been ready for a while),
+    //     prefer that over re-booting through the bridge.
     const n8n = config.n8n;
     if (n8n?.host && n8n?.apiKey) {
         if (!process.env.N8N_HOST)
@@ -1203,7 +1230,33 @@ export function applyN8nConfigToEnv(config, agentId) {
             process.env.N8N_API_KEY = n8n.apiKey;
         return;
     }
-    // 3. Fallback — leave unset. Legacy `config.env.vars` entries (N8N_HOST /
+    // 3. Local sidecar. Skip on mobile (no child_process).
+    if (isMobilePlatform()) {
+        logger.info("[N8nSidecar] Skipping (mobile platform)");
+        return;
+    }
+    if (n8n?.localEnabled === false) {
+        return;
+    }
+    try {
+        const { bootLocalN8nSidecar } = await import("./n8n-sidecar-bridge.js");
+        const booted = await bootLocalN8nSidecar({
+            enabled: true,
+            version: n8n?.version,
+            startPort: n8n?.startPort,
+        });
+        if (booted) {
+            if (!process.env.N8N_HOST)
+                process.env.N8N_HOST = booted.host;
+            if (!process.env.N8N_API_KEY)
+                process.env.N8N_API_KEY = booted.apiKey;
+            return;
+        }
+    }
+    catch (err) {
+        logger.warn(`[N8nSidecar] bridge crashed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // 4. Fallback — leave unset. Legacy `config.env.vars` entries (N8N_HOST /
     //    N8N_API_KEY) still flow through the generic env-var pump in startEliza.
 }
 function resolveDefaultPgliteDataDir(config) {
@@ -2406,10 +2459,11 @@ export async function startEliza(opts) {
     await autoFetchCloudGithubToken(config.cloud?.agentId?.trim() || agentId);
     // 5b. Pump N8N_HOST + N8N_API_KEY into process.env for
     //     @elizaos/plugin-n8n-workflow. Must run AFTER applyCloudConfigToEnv
-    //     (2b above) and AFTER agentId is derived — the cloud gateway URL
-    //     embeds the agent id. Prefer the persisted cloud-agent id when set;
-    //     fall back to the derived local agent slug.
-    applyN8nConfigToEnv(config, config.cloud?.agentId?.trim() || agentId);
+    //     (2b above) and BEFORE plugin resolution so the n8n plugin's init()
+    //     reads populated env. The resolver mints a Cloud-scoped n8n token
+    //     when cloud is paired, and otherwise boots the local sidecar via
+    //     @elizaos/app-core/services/n8n-sidecar and waits for readiness.
+    await applyN8nConfigToEnv(config, config.cloud?.agentId?.trim() || agentId);
     const elizaPlugin = createElizaPlugin({
         workspaceDir,
         agentId,
@@ -2821,12 +2875,14 @@ export async function startEliza(opts) {
         }
     };
     const initializeRuntimeServices = async () => {
-        try {
-            const { stewardEvmPreBoot } = await import("@elizaos/app-steward/services/steward-evm-bridge");
-            await stewardEvmPreBoot(runtime);
-        }
-        catch (err) {
-            logger.debug(`[eliza] Steward EVM pre-boot skipped: ${formatError(err)}`);
+        if (process.env.ELIZA_LEGACY_STEWARD_EVM_BRIDGE !== "0") {
+            try {
+                const { stewardEvmPreBoot } = await import("@elizaos/app-steward/services/steward-evm-bridge");
+                await stewardEvmPreBoot(runtime);
+            }
+            catch (err) {
+                logger.debug(`[eliza] Steward EVM pre-boot skipped: ${formatError(err)}`);
+            }
         }
         // 7f. Pre-register ConnectorSetupService so connector plugins can access
         //     shared config/escalation/owner-contact helpers via runtime.getService().
@@ -2892,12 +2948,14 @@ export async function startEliza(opts) {
         catch (err) {
             logger.warn(`[eliza] Failed to seed bundled knowledge: ${formatError(err)}`);
         }
-        try {
-            const { stewardEvmPostBoot } = await import("@elizaos/app-steward/services/steward-evm-bridge");
-            await stewardEvmPostBoot(runtime);
-        }
-        catch (err) {
-            logger.debug(`[eliza] Steward EVM post-boot skipped: ${formatError(err)}`);
+        if (process.env.ELIZA_LEGACY_STEWARD_EVM_BRIDGE !== "0") {
+            try {
+                const { stewardEvmPostBoot } = await import("@elizaos/app-steward/services/steward-evm-bridge");
+                await stewardEvmPostBoot(runtime);
+            }
+            catch (err) {
+                logger.debug(`[eliza] Steward EVM post-boot skipped: ${formatError(err)}`);
+            }
         }
         try {
             const { installAnthropicWebSearch } = await import("./web-search-tools.js");
@@ -3073,7 +3131,7 @@ export async function startEliza(opts) {
                     applyCloudConfigToEnv(freshConfig);
                     applyX402ConfigToEnv(freshConfig);
                     applyDatabaseConfigToEnv(freshConfig);
-                    applyN8nConfigToEnv(freshConfig, freshConfig.cloud?.agentId?.trim() || agentId);
+                    await applyN8nConfigToEnv(freshConfig, freshConfig.cloud?.agentId?.trim() || agentId);
                     await autoFetchCloudGithubToken(freshConfig.cloud?.agentId?.trim() || agentId);
                     // Apply subscription-based credentials (Claude Max, Codex Max)
                     // that may have been set up during onboarding.

package/packages/agent/src/runtime/first-time-setup.d.ts

@@ -28,7 +28,7 @@ export declare function applyFirstTimeSetupTopology(config: ElizaConfig, args: {
 }): ElizaConfig;
 /**
  * When cloud mode + cloud wallet are both on and the cloud cache holds
- * descriptors, mark the runtime env so plugin-evm / plugin-solana bind
+ * descriptors, mark the runtime env so plugin-wallet binds
  * against the cloud signer rather than a local private key. Writes
  * `WALLET_SOURCE_EVM=cloud` / `WALLET_SOURCE_SOLANA=cloud` and the resolved
  * cloud wallet addresses to config.env (durable across restarts) and to

package/packages/agent/src/runtime/first-time-setup.js

@@ -151,7 +151,7 @@ function readUserPrimarySelection(config) {
 }
 /**
  * When cloud mode + cloud wallet are both on and the cloud cache holds
- * descriptors, mark the runtime env so plugin-evm / plugin-solana bind
+ * descriptors, mark the runtime env so plugin-wallet binds
  * against the cloud signer rather than a local private key. Writes
  * `WALLET_SOURCE_EVM=cloud` / `WALLET_SOURCE_SOLANA=cloud` and the resolved
  * cloud wallet addresses to config.env (durable across restarts) and to
@@ -673,7 +673,7 @@ export async function runFirstTimeSetup(config) {
     }
     // If cloud-mode onboarding already left cloud-wallet descriptors in the
     // config (rare on first run, but possible when resuming a partial flow),
-    // make sure plugin-evm / plugin-solana see WALLET_SOURCE_*=cloud before
+    // make sure plugin-wallet sees WALLET_SOURCE_*=cloud before
     // they load.
     try {
         await bindCloudProvider(topologyUpdated);

package/packages/agent/src/runtime/n8n-cloud-resolver.d.ts

@@ -0,0 +1,42 @@
+export interface MintedN8nToken {
+    token: string;
+    expiresAt: string;
+    cloudBaseUrl: string;
+}
+export interface ResolvedN8nCloud {
+    /** Gateway URL the n8n plugin should use as `N8N_HOST`. */
+    host: string;
+    /** Minted scoped token to use as `N8N_API_KEY`. NOT the cloud key. */
+    apiKey: string;
+}
+interface ResolverDeps {
+    fetch?: typeof fetch;
+    /** Override the cache file location. Default `<stateDir>/n8n/cloud-token.json`. */
+    cachePath?: string;
+    /** Current wall-clock time. Injected for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * Strip `/api/v1/?$` and trailing slashes from a cloud base URL so we can
+ * append our own `/api/v1/...` segments without duplication.
+ */
+declare function normalizeCloudBase(rawBase: string): string;
+declare function defaultCachePath(stateDir: string): string;
+/**
+ * Resolve the n8n cloud gateway URL + minted token.
+ *
+ * Returns `{ host, apiKey }` on success or `null` when the caller should
+ * fall through to the local sidecar (404, 401/403, repeated network failures,
+ * malformed response).
+ *
+ * On success, the host is `${cloudBaseUrl}/api/v1/n8n` (per gateway contract
+ * §2 and §5). The apiKey is the minted scoped token, never the cloud key.
+ */
+export declare function resolveN8nCloudToken(cloudApiKey: string, cloudBaseUrlRaw: string, stateDir: string, deps?: ResolverDeps): Promise<ResolvedN8nCloud | null>;
+export declare const __testing: {
+    defaultCachePath: typeof defaultCachePath;
+    normalizeCloudBase: typeof normalizeCloudBase;
+    CACHE_REUSE_MIN_MS_REMAINING: number;
+};
+export {};
+//# sourceMappingURL=n8n-cloud-resolver.d.ts.map

package/packages/agent/src/runtime/n8n-cloud-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"n8n-cloud-resolver.d.ts","sourceRoot":"","sources":["../../../../../../agent/src/runtime/n8n-cloud-resolver.ts"],"names":[],"mappings":"AAoCA,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,iBAAS,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAInD;AAED,iBAAS,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElD;AAgID;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAwElC;AAGD,eAAO,MAAM,SAAS;;;;CAIrB,CAAC"}

package/packages/agent/src/runtime/n8n-cloud-resolver.js

@@ -0,0 +1,211 @@
+/**
+ * n8n cloud-token resolver.
+ *
+ * Mints a short-lived n8n API token from the Eliza Cloud gateway via
+ * `POST {cloudBaseUrl}/api/v1/n8n/tokens` (auth: `Bearer <ELIZAOS_CLOUD_API_KEY>`).
+ * The full Cloud key is NEVER passed through to the n8n plugin as
+ * `N8N_API_KEY` — only the minted token. See
+ * `docs/cloud/n8n-gateway-contract.md` (§4) for the wire shape.
+ *
+ * Cache file: `<stateDir>/n8n/cloud-token.json` containing
+ *   { token, expiresAt, cloudBaseUrl }.
+ *
+ * The cache is reused if `expiresAt` is more than `CACHE_REUSE_MIN_MS_REMAINING`
+ * in the future AND `cloudBaseUrl` matches the current resolved base. Otherwise
+ * the resolver mints a fresh token, persists it mode-0600, and returns it.
+ *
+ * Failure modes (intentional):
+ *   - 404 from the gateway endpoint: the gateway isn't deployed yet. Log
+ *     `info` and return `null` so the caller falls through to the local
+ *     sidecar.
+ *   - 401/403: the cloud key is invalid or the user lacks the n8n product.
+ *     Log `error` and return `null`.
+ *   - Network error / timeout: retried once, then `warn` + `null` so the
+ *     caller falls through to the local sidecar.
+ *
+ * @module n8n-cloud-resolver
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { logger } from "@elizaos/core";
+const LOG_PREFIX = "[N8nCloudResolver]";
+const FETCH_TIMEOUT_MS = 5_000;
+const CACHE_REUSE_MIN_MS_REMAINING = 60_000;
+/**
+ * Strip `/api/v1/?$` and trailing slashes from a cloud base URL so we can
+ * append our own `/api/v1/...` segments without duplication.
+ */
+function normalizeCloudBase(rawBase) {
+    // Defensive cap to avoid pathological config strings.
+    const safeBase = rawBase.length > 8192 ? rawBase.slice(0, 8192) : rawBase;
+    return safeBase.replace(/\/api\/v1\/?$/, "").replace(/\/{1,1024}$/, "");
+}
+function defaultCachePath(stateDir) {
+    return path.join(stateDir, "n8n", "cloud-token.json");
+}
+async function readCache(cachePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(cachePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const candidate = parsed;
+    if (typeof candidate.token !== "string" ||
+        typeof candidate.expiresAt !== "string" ||
+        typeof candidate.cloudBaseUrl !== "string" ||
+        candidate.token.length === 0 ||
+        candidate.expiresAt.length === 0 ||
+        candidate.cloudBaseUrl.length === 0) {
+        return null;
+    }
+    return {
+        token: candidate.token,
+        expiresAt: candidate.expiresAt,
+        cloudBaseUrl: candidate.cloudBaseUrl,
+    };
+}
+async function writeCache(cachePath, token) {
+    const dir = path.dirname(cachePath);
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    // Re-chmod defensively — `mkdir` mode is masked by umask on some platforms.
+    await fs.chmod(dir, 0o700).catch(() => undefined);
+    await fs.writeFile(cachePath, JSON.stringify(token, null, 2), {
+        mode: 0o600,
+    });
+    await fs.chmod(cachePath, 0o600).catch(() => undefined);
+}
+async function callMintEndpoint(fetchImpl, cloudBaseUrl, cloudApiKey) {
+    const url = `${cloudBaseUrl}/api/v1/n8n/tokens`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${cloudApiKey}`,
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            body: JSON.stringify({ purpose: "milady-runtime" }),
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        return {
+            transient: {
+                reason: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+    if (res.status === 404) {
+        return { notDeployed: true };
+    }
+    if (res.status === 401 || res.status === 403) {
+        return { authFailed: { status: res.status } };
+    }
+    if (res.status >= 500 && res.status < 600) {
+        return { transient: { reason: `gateway ${res.status}` } };
+    }
+    if (!res.ok) {
+        return { permanent: { status: res.status } };
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch (err) {
+        return {
+            transient: {
+                reason: `JSON parse error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    if (!body || typeof body !== "object") {
+        return { transient: { reason: "non-object response body" } };
+    }
+    const candidate = body;
+    if (typeof candidate.token !== "string" ||
+        typeof candidate.expiresAt !== "string" ||
+        candidate.token.length === 0 ||
+        candidate.expiresAt.length === 0) {
+        return { transient: { reason: "missing token/expiresAt in response" } };
+    }
+    return { ok: { token: candidate.token, expiresAt: candidate.expiresAt } };
+}
+/**
+ * Resolve the n8n cloud gateway URL + minted token.
+ *
+ * Returns `{ host, apiKey }` on success or `null` when the caller should
+ * fall through to the local sidecar (404, 401/403, repeated network failures,
+ * malformed response).
+ *
+ * On success, the host is `${cloudBaseUrl}/api/v1/n8n` (per gateway contract
+ * §2 and §5). The apiKey is the minted scoped token, never the cloud key.
+ */
+export async function resolveN8nCloudToken(cloudApiKey, cloudBaseUrlRaw, stateDir, deps = {}) {
+    const fetchImpl = deps.fetch ?? fetch;
+    const now = deps.now ?? (() => Date.now());
+    const cloudBaseUrl = normalizeCloudBase(cloudBaseUrlRaw);
+    const cachePath = deps.cachePath ?? defaultCachePath(stateDir);
+    const host = `${cloudBaseUrl}/api/v1/n8n`;
+    // Try the cache first.
+    const cached = await readCache(cachePath);
+    if (cached && cached.cloudBaseUrl === cloudBaseUrl) {
+        const expiresAtMs = Date.parse(cached.expiresAt);
+        if (Number.isFinite(expiresAtMs) &&
+            expiresAtMs - now() > CACHE_REUSE_MIN_MS_REMAINING) {
+            return { host, apiKey: cached.token };
+        }
+    }
+    // Mint a fresh token. Retry once on transient failure (network/5xx).
+    let attempt = await callMintEndpoint(fetchImpl, cloudBaseUrl, cloudApiKey);
+    if (attempt.transient) {
+        logger.debug(`${LOG_PREFIX} mint transient failure (${attempt.transient.reason}); retrying once`);
+        attempt = await callMintEndpoint(fetchImpl, cloudBaseUrl, cloudApiKey);
+    }
+    if (attempt.ok) {
+        const minted = {
+            token: attempt.ok.token,
+            expiresAt: attempt.ok.expiresAt,
+            cloudBaseUrl,
+        };
+        try {
+            await writeCache(cachePath, minted);
+        }
+        catch (err) {
+            logger.warn(`${LOG_PREFIX} failed to persist token cache: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        logger.info(`${LOG_PREFIX} Resolved via cloud-gateway`);
+        return { host, apiKey: minted.token };
+    }
+    if (attempt.notDeployed) {
+        logger.info(`${LOG_PREFIX} gateway endpoint /api/v1/n8n/tokens returned 404 — falling through to local sidecar`);
+        return null;
+    }
+    if (attempt.authFailed) {
+        logger.error(`${LOG_PREFIX} cloud auth rejected (${attempt.authFailed.status}) — falling through to local sidecar`);
+        return null;
+    }
+    if (attempt.permanent) {
+        logger.error(`${LOG_PREFIX} unexpected gateway status ${attempt.permanent.status} — falling through to local sidecar`);
+        return null;
+    }
+    logger.warn(`${LOG_PREFIX} gateway unreachable after retry (${attempt.transient?.reason ?? "unknown"}) — falling through to local sidecar`);
+    return null;
+}
+// Re-exported helper so tests can build deterministic state paths.
+export const __testing = {
+    defaultCachePath,
+    normalizeCloudBase,
+    CACHE_REUSE_MIN_MS_REMAINING,
+};

package/packages/agent/src/runtime/n8n-sidecar-bridge.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Bridge from the agent runtime to the app-core n8n sidecar.
+ *
+ * The local n8n sidecar implementation lives at
+ * `@elizaos/app-core/services/n8n-sidecar` (single source of truth: lifecycle,
+ * REST-based owner setup, API-key provisioning, free-port picker, orphan
+ * detection). The agent package can't statically import app-core (app-core
+ * already depends on agent — it would be a cycle), so we dynamic-import
+ * lazily here so the agent's `applyN8nConfigToEnv` can drive sidecar
+ * readiness inline before the n8n plugin is loaded.
+ *
+ * Mobile platforms cannot spawn a child process; the caller must guard with
+ * the platform check before invoking this bridge.
+ *
+ * @module n8n-sidecar-bridge
+ */
+export interface SidecarBootResult {
+    host: string;
+    apiKey: string;
+}
+interface SidecarLike {
+    start: () => Promise<void>;
+    getState: () => {
+        status: "stopped" | "starting" | "ready" | "error";
+        host: string | null;
+        errorMessage: string | null;
+    };
+    getApiKey: () => string | null;
+    subscribe: (fn: (state: {
+        status: "stopped" | "starting" | "ready" | "error";
+    }) => void) => () => void;
+}
+interface SidecarModule {
+    getN8nSidecarAsync: (config: {
+        enabled?: boolean;
+        version?: string;
+        startPort?: number;
+    }) => Promise<SidecarLike>;
+    peekN8nSidecar: () => SidecarLike | null;
+}
+export interface BootSidecarOptions {
+    enabled?: boolean;
+    version?: string;
+    startPort?: number;
+    /** Timeout in ms to wait for "ready" or "error". Default 60s. */
+    readinessTimeoutMs?: number;
+    /** Override the dynamic loader for tests. */
+    loadModule?: () => Promise<SidecarModule>;
+}
+/**
+ * Ensure the local n8n sidecar is ready, returning its host + apiKey.
+ *
+ * - If the sidecar is already `ready`, returns its current values without
+ *   re-spawning.
+ * - Otherwise starts the sidecar via `getN8nSidecarAsync().start()` and
+ *   awaits the next `ready`/`error` transition (bounded by
+ *   `readinessTimeoutMs`).
+ * - Returns `null` if the sidecar lands in `error` or the timeout expires —
+ *   the caller logs and falls through to "disabled" (the n8n plugin's
+ *   init() will warn, which is the correct behavior when both cloud and
+ *   local are unavailable).
+ *
+ * Caller must have already verified that the runtime is not on a mobile
+ * platform; we do not re-check here.
+ */
+export declare function bootLocalN8nSidecar(options?: BootSidecarOptions): Promise<SidecarBootResult | null>;
+export {};
+//# sourceMappingURL=n8n-sidecar-bridge.d.ts.map

package/packages/agent/src/runtime/n8n-sidecar-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"n8n-sidecar-bridge.d.ts","sourceRoot":"","sources":["../../../../../../agent/src/runtime/n8n-sidecar-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,QAAQ,EAAE,MAAM;QACd,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;QACnD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;IACF,SAAS,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,EAAE,CACT,EAAE,EAAE,CAAC,KAAK,EAAE;QACV,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;KACpD,KAAK,IAAI,KACP,MAAM,IAAI,CAAC;CACjB;AAED,UAAU,aAAa;IACrB,kBAAkB,EAAE,CAAC,MAAM,EAAE;QAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3B,cAAc,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;CAC1C;AAaD,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAoGnC"}