@walkeros/mcp 4.6.0 → 4.6.1

package/dist/index.js

@@ -1,3 +1,98 @@
+// src/cloud-flow.ts
+import { isObject } from "@walkeros/core";
+var CLOUD_ID_PATTERN = /^(flow|cfg)_[A-Za-z0-9_-]+$/;
+function isCloudId(input) {
+  return CLOUD_ID_PATTERN.test(input);
+}
+function flowConfigOf(flow) {
+  return isObject(flow) && isObject(flow.config) ? flow.config : {};
+}
+
+// src/runtime/types.ts
+var RuntimeRefusal = class extends Error {
+  hint;
+  constructor(message, hint) {
+    super(message);
+    this.name = "RuntimeRefusal";
+    this.hint = hint;
+  }
+};
+function refusalHint(error, fallback) {
+  return error instanceof RuntimeRefusal ? error.hint : fallback;
+}
+var HINT_OUT_OF_PROCESS = "Build and deploy through the app with deploy_manage, or simulate the flow in the app. On your own machine, use the walkerOS CLI.";
+function unavailableOperation(operation) {
+  const verb = operation === "bundle" ? "Bundling" : operation === "simulate" ? "Simulating" : "Running";
+  return new RuntimeRefusal(
+    `${verb} a flow is not available on the hosted walkerOS MCP server.`,
+    HINT_OUT_OF_PROCESS
+  );
+}
+
+// src/runtime/hosted.ts
+function isHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function looksLikePath(value) {
+  return /[\\/]/.test(value) || value.startsWith(".") || /\.[A-Za-z0-9]+$/.test(value);
+}
+function classifyConfigInput(input) {
+  const trimmed = input.trim();
+  if (isHttpUrl(trimmed)) return "url";
+  if (isCloudId(trimmed)) return "cloud-id";
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) return "inline-json";
+  if (looksLikePath(trimmed)) return "local-path";
+  return "bare-string";
+}
+var HINT_INLINE_OR_ID = "Pass the flow inline as JSON, or reference a saved flow by its flow_ or cfg_ id.";
+function refuseLocalPath() {
+  return new RuntimeRefusal(
+    "Local file paths are not available on the hosted walkerOS MCP server.",
+    HINT_INLINE_OR_ID
+  );
+}
+function refuseUrl() {
+  return new RuntimeRefusal(
+    "Fetching URLs is not available on the hosted walkerOS MCP server.",
+    HINT_INLINE_OR_ID
+  );
+}
+function parseInline(trimmed) {
+  try {
+    return JSON.parse(trimmed);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Input appears to be JSON but contains errors: ${message}`);
+  }
+}
+function createHostedRuntime(client) {
+  return {
+    async load(input) {
+      const trimmed = input.trim();
+      if (trimmed === "") throw new Error("Input is required");
+      switch (classifyConfigInput(trimmed)) {
+        case "url":
+          throw refuseUrl();
+        case "cloud-id":
+          return flowConfigOf(await client.getFlow({ flowId: trimmed }));
+        case "inline-json":
+          return parseInline(trimmed);
+        case "local-path":
+          throw refuseLocalPath();
+        case "bare-string":
+          throw new Error(
+            `Cannot resolve "${trimmed}" on the hosted walkerOS MCP server. ${HINT_INLINE_OR_ID}`
+          );
+      }
+    }
+  };
+}
+
 // src/tools/auth.ts
 import { z } from "zod";
 import { mcpResult, mcpError } from "@walkeros/core";
@@ -2738,7 +2833,7 @@ async function feedbackHandlerBody(client, input) {
     const isAnonymous = explicitAnonymous ?? anonymous ?? true;
     await client.submitFeedback(text, {
       anonymous: isAnonymous,
-      version: "4.6.0"
+      version: "4.6.1"
     });
     return mcpResult10({ ok: true });
   } catch (error) {
@@ -2762,7 +2857,7 @@ function registerFeedbackTool(server, client) {
 }
 
 // src/tools/validate.ts
-import { validate, loadJsonConfig } from "@walkeros/cli";
+import { validate } from "@walkeros/cli";
 import { schemas } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult11, mcpError as mcpError11 } from "@walkeros/core";
 
@@ -2857,6 +2952,22 @@ var ExamplesListOutputShape = {
 };
 
 // src/tools/validate.ts
+async function loadValidateInput(runtime, input, type) {
+  if (!input || input.trim() === "") throw new Error(`${type} is required`);
+  const trimmed = input.trim();
+  const looksLikeJson = trimmed.startsWith("{") || trimmed.startsWith("[");
+  try {
+    return await runtime.load(input);
+  } catch (error) {
+    if (error instanceof RuntimeRefusal || isCloudId(trimmed)) throw error;
+    if (looksLikeJson) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to parse ${type}. ${message}`);
+    }
+    if (type === "event") return { name: trimmed };
+    throw error;
+  }
+}
 var DEPRECATED_STORE_PACKAGE = "@walkeros/store-memory";
 function detectDeprecatedStorePackages(config) {
   const errors = [];
@@ -2886,7 +2997,7 @@ function detectDeprecatedStorePackages(config) {
   return errors;
 }
 var TITLE11 = "Validate Flow";
-var DESCRIPTION9 = "Validate walkerOS events, flow configurations, mapping rules, or data contracts. Accepts JSON strings, file paths, or URLs as input. Returns validation results with errors, warnings, and details.";
+var DESCRIPTION9 = "Validate walkerOS events, flow configurations, mapping rules, or data contracts. Accepts JSON strings, file paths, or URLs as input; on the hosted server only inline JSON or a saved flow id (flow_ or cfg_), no file paths or URLs. Returns validation results with errors, warnings, and details.";
 var inputSchema9 = schemas.ValidateInputShape;
 var annotations11 = {
   readOnlyHint: true,
@@ -2894,17 +3005,17 @@ var annotations11 = {
   idempotentHint: true,
   openWorldHint: false
 };
-function createFlowValidateToolSpec() {
+function createFlowValidateToolSpec(runtime) {
   return {
     name: "flow_validate",
     title: TITLE11,
     description: DESCRIPTION9,
     inputSchema: inputSchema9,
     annotations: annotations11,
-    handler: (input) => flowValidateHandlerBody(input)
+    handler: (input) => flowValidateHandlerBody(runtime, input)
   };
 }
-async function flowValidateHandlerBody(input) {
+async function flowValidateHandlerBody(runtime, input) {
   const {
     type,
     input: validateInput,
@@ -2912,30 +3023,27 @@ async function flowValidateHandlerBody(input) {
     path: path2
   } = input ?? {};
   try {
-    const result = await validate(type, validateInput, {
+    const resolved = await loadValidateInput(runtime, validateInput, type);
+    const result = await validate(type, resolved, {
       flow,
       path: path2
     });
     let augmented = result;
-    if (type === "flow" && typeof validateInput === "string") {
-      try {
-        const config = await loadJsonConfig(validateInput);
-        const deprecatedErrors = detectDeprecatedStorePackages(config);
-        if (deprecatedErrors.length > 0) {
-          augmented = {
-            ...result,
-            valid: false,
-            errors: [...result.errors, ...deprecatedErrors]
-          };
-        }
-      } catch {
+    if (type === "flow") {
+      const deprecatedErrors = detectDeprecatedStorePackages(resolved);
+      if (deprecatedErrors.length > 0) {
+        augmented = {
+          ...result,
+          valid: false,
+          errors: [...result.errors, ...deprecatedErrors]
+        };
       }
     }
     const hints = augmented.valid ? {
-      next: [
+      next: runtime.simulate ? [
         "Use flow_simulate to test event flow",
         "Use flow_bundle to build"
-      ]
+      ] : [HINT_OUT_OF_PROCESS]
     } : {
       next: [
         "Fix errors above, then run flow_validate again",
@@ -2946,12 +3054,15 @@ async function flowValidateHandlerBody(input) {
   } catch (error) {
     return mcpError11(
       error,
-      "Check the input parameter \u2014 expected a JSON string, file path, or URL"
+      refusalHint(
+        error,
+        "Check the input parameter \u2014 expected a JSON string, file path, or URL"
+      )
     );
   }
 }
-function registerFlowValidateTool(server) {
-  const spec = createFlowValidateToolSpec();
+function registerFlowValidateTool(server, runtime) {
+  const spec = createFlowValidateToolSpec(runtime);
   server.registerTool(
     spec.name,
     {
@@ -2969,17 +3080,14 @@ function registerFlowValidateTool(server) {
 }
 
 // src/tools/bundle.ts
-import { bundle } from "@walkeros/cli";
 import { schemas as schemas2 } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult12, mcpError as mcpError12 } from "@walkeros/core";
 
 // src/tools/resolve-config-path.ts
-var API_ID_PREFIX = /^(flow|cfg)_/;
 async function resolveConfigPath(client, configPath) {
-  if (!API_ID_PREFIX.test(configPath)) return configPath;
+  if (!isCloudId(configPath)) return configPath;
   const flow = await client.getFlow({ flowId: configPath });
-  const config = flow.config;
-  return JSON.stringify(config ?? {});
+  return JSON.stringify(flowConfigOf(flow));
 }
 
 // src/tools/bundle.ts
@@ -2994,24 +3102,28 @@ var annotations12 = {
   idempotentHint: false,
   openWorldHint: true
 };
-function createFlowBundleToolSpec(client) {
+function createFlowBundleToolSpec(client, runtime) {
   return {
     name: "flow_bundle",
     title: TITLE12,
     description: DESCRIPTION10,
     inputSchema: inputSchema10,
     annotations: annotations12,
-    handler: (input) => flowBundleHandlerBody(client, input)
+    handler: (input) => flowBundleHandlerBody(client, runtime, input)
   };
 }
-async function flowBundleHandlerBody(client, input) {
+async function flowBundleHandlerBody(client, runtime, input) {
   const { configPath, flow, stats, output } = input ?? {};
+  if (!runtime.bundle) {
+    const refusal = unavailableOperation("bundle");
+    return mcpError12(refusal, refusal.hint);
+  }
   try {
     const resolvedConfigPath = await resolveConfigPath(client, configPath);
-    const result = await bundle(resolvedConfigPath, {
+    const result = await runtime.bundle(resolvedConfigPath, {
       flowName: flow,
       stats: stats ?? true,
-      buildOverrides: output ? { output } : void 0
+      output
     });
     if (!result) {
       return mcpResult12(
@@ -3035,11 +3147,14 @@ async function flowBundleHandlerBody(client, input) {
       }
     );
   } catch (error) {
-    return mcpError12(error, "Run flow_validate for detailed error messages");
+    return mcpError12(
+      error,
+      refusalHint(error, "Run flow_validate for detailed error messages")
+    );
   }
 }
-function registerFlowBundleTool(server, client) {
-  const spec = createFlowBundleToolSpec(client);
+function registerFlowBundleTool(server, client, runtime) {
+  const spec = createFlowBundleToolSpec(client, runtime);
   server.registerTool(
     spec.name,
     {
@@ -3058,101 +3173,17 @@ function registerFlowBundleTool(server, client) {
 
 // src/tools/simulate.ts
 import { z as z12 } from "zod";
-import {
-  simulateSource,
-  simulateTransformer,
-  simulateDestination,
-  simulateCollector
-} from "@walkeros/cli";
 import { schemas as schemas3 } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult13, mcpError as mcpError13 } from "@walkeros/core";
-
-// src/tools/bundle-cache.ts
-import { createHash } from "crypto";
-import os from "os";
-import path from "path";
-import { mkdir, rm, writeFile } from "fs/promises";
-import { rmSync } from "fs";
-import { bundle as bundle2 } from "@walkeros/cli";
-var MAX_ENTRIES = 8;
-var cache = /* @__PURE__ */ new Map();
-var inFlight = /* @__PURE__ */ new Map();
-var cleanupRegistered = false;
-function hashConfig(resolvedConfig) {
-  return createHash("sha256").update(resolvedConfig).digest("hex");
-}
-function isInlineJsonConfig(resolvedConfig) {
-  const trimmed = resolvedConfig.trimStart();
-  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return false;
-  try {
-    JSON.parse(resolvedConfig);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function registerProcessCleanup() {
-  if (cleanupRegistered) return;
-  cleanupRegistered = true;
-  const cleanup = () => {
-    for (const entry of cache.values()) {
-      try {
-        rmSync(entry.dir, { recursive: true, force: true });
-      } catch {
-      }
-    }
-    cache.clear();
-  };
-  process.once("exit", cleanup);
-}
-async function evictIfNeeded() {
-  while (cache.size > MAX_ENTRIES) {
-    const oldestKey = cache.keys().next().value;
-    if (oldestKey === void 0) break;
-    const evicted = cache.get(oldestKey);
-    cache.delete(oldestKey);
-    if (evicted) await rm(evicted.dir, { recursive: true, force: true });
-  }
-}
-async function getOrBuildBundle(resolvedConfig) {
-  if (!isInlineJsonConfig(resolvedConfig)) return void 0;
-  registerProcessCleanup();
-  const key = hashConfig(resolvedConfig);
-  const cached = cache.get(key);
-  if (cached) {
-    cache.delete(key);
-    cache.set(key, cached);
-    return cached.bundlePath;
-  }
-  const pending = inFlight.get(key);
-  if (pending) return pending;
-  const build = (async () => {
-    const dir = path.join(
-      os.tmpdir(),
-      `walkeros-mcp-bundle-${key.slice(0, 16)}`
-    );
-    await rm(dir, { recursive: true, force: true });
-    await mkdir(dir, { recursive: true });
-    const bundlePath = path.join(dir, "flow.mjs");
-    await writeFile(bundlePath, "", "utf-8");
-    await bundle2(resolvedConfig, {
-      target: "simulate",
-      silent: true,
-      buildOverrides: { output: bundlePath, format: "esm", minify: false }
-    });
-    cache.set(key, { bundlePath, dir });
-    await evictIfNeeded();
-    return bundlePath;
-  })();
-  inFlight.set(key, build);
-  try {
-    return await build;
-  } finally {
-    inFlight.delete(key);
-  }
+var STEP_TYPES = [
+  "source",
+  "transformer",
+  "collector",
+  "destination"
+];
+function isStepType(value) {
+  return STEP_TYPES.some((t) => t === value);
 }
-
-// src/tools/simulate.ts
 var TITLE13 = "Simulate Flow";
 var DESCRIPTION11 = 'Simulate events through a walkerOS flow without making real API calls. For destinations: event is a walkerOS event { name: "entity action", data: {...} }. For sources: event is { content, trigger?: { type?, options? } }, where content is the walkerOS event { name: "entity action", data: {...} }. step (required) targets the step to simulate, e.g. "destination.gtag". Use flow_examples to discover available test data. IMPORTANT: Destinations with require (e.g. require: ["consent"]) stay pending until that collector event fires \u2014 simulation will error "not found" if require is not satisfied. Remove require from config or provide consent/user events before simulating. Separately, destinations with consent (e.g. consent: { marketing: true }) only receive events where the event includes matching consent. Mapping transforms event names and data at the destination level. Policy redacts or injects fields before mapping runs.';
 var inputSchema11 = {
@@ -3181,23 +3212,31 @@ var inputSchema11 = {
   )
 };
 var annotations13 = {
-  readOnlyHint: true,
-  destructiveHint: false,
-  idempotentHint: true,
-  openWorldHint: false
+  // Simulation downloads the packages a config names and runs caller-controlled
+  // flow code in process. Destinations are mocked, but that code is not, so the
+  // hints stay conservative: side effects possible, repeat calls not assumed
+  // safe, external systems reachable.
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: true
 };
-function createFlowSimulateToolSpec(client) {
+function createFlowSimulateToolSpec(client, runtime) {
   return {
     name: "flow_simulate",
     title: TITLE13,
     description: DESCRIPTION11,
     inputSchema: inputSchema11,
     annotations: annotations13,
-    handler: (input) => flowSimulateHandlerBody(client, input)
+    handler: (input) => flowSimulateHandlerBody(client, runtime, input)
   };
 }
-async function flowSimulateHandlerBody(client, input) {
+async function flowSimulateHandlerBody(client, runtime, input) {
   const { configPath, event, flow, platform, step, verbose, ingest, state } = input ?? {};
+  if (!runtime.simulate) {
+    const refusal = unavailableOperation("simulate");
+    return mcpError13(refusal, refusal.hint);
+  }
   try {
     if (!event) {
       throw new Error(
@@ -3227,66 +3266,16 @@ async function flowSimulateHandlerBody(client, input) {
     }
     const stepType = step.substring(0, dotIndex);
     const stepId = step.substring(dotIndex + 1);
-    const resolvedConfigPath = await resolveConfigPath(client, configPath);
-    let bundlePath;
-    try {
-      bundlePath = await getOrBuildBundle(resolvedConfigPath);
-    } catch {
-      bundlePath = void 0;
-    }
-    let result;
-    switch (stepType) {
-      case "source":
-        result = await simulateSource(resolvedConfigPath, resolvedEvent, {
-          sourceId: stepId,
-          bundlePath,
-          flow,
-          silent: true
-        });
-        break;
-      case "transformer":
-        result = await simulateTransformer(
-          resolvedConfigPath,
-          resolvedEvent,
-          {
-            transformerId: stepId,
-            bundlePath,
-            flow,
-            silent: true,
-            ingest
-          }
-        );
-        break;
-      case "collector":
-        result = await simulateCollector(
-          resolvedConfigPath,
-          resolvedEvent,
-          {
-            collectorName: stepId,
-            bundlePath,
-            flow,
-            silent: true,
-            state
-          }
-        );
-        break;
-      case "destination":
-        result = await simulateDestination(
-          resolvedConfigPath,
-          resolvedEvent,
-          {
-            destinationId: stepId,
-            bundlePath,
-            flow,
-            silent: true
-          }
-        );
-        break;
-      default:
-        throw new Error(
-          `Unknown step type "${stepType}". Use "source", "collector", "transformer", or "destination".`
-        );
+    if (!isStepType(stepType)) {
+      throw new Error(
+        `Unknown step type "${stepType}". Use "source", "collector", "transformer", or "destination".`
+      );
     }
+    const resolvedConfigPath = await resolveConfigPath(client, configPath);
+    const result = await runtime.simulate(
+      resolvedConfigPath,
+      { stepType, stepId, event: resolvedEvent, flow, ingest, state }
+    );
     const success = !result.error;
     const errorMessage = result.error?.message;
     if (result.step === "source") {
@@ -3374,11 +3363,11 @@ async function flowSimulateHandlerBody(client, input) {
     if (msg.includes("not found in collector")) {
       hint = 'If this destination has require: ["consent"] or require: ["user"], it stays pending until that event fires. For simulation, either remove require from the config or simulate with a flow that omits require on the target destination.';
     }
-    return mcpError13(error, hint);
+    return mcpError13(error, refusalHint(error, hint));
   }
 }
-function registerFlowSimulateTool(server, client) {
-  const spec = createFlowSimulateToolSpec(client);
+function registerFlowSimulateTool(server, client, runtime) {
+  const spec = createFlowSimulateToolSpec(client, runtime);
   server.registerTool(
     spec.name,
     {
@@ -3397,7 +3386,6 @@ function registerFlowSimulateTool(server, client) {
 
 // src/tools/push.ts
 import { z as z13 } from "zod";
-import { push } from "@walkeros/cli";
 import { schemas as schemas4 } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult14, mcpError as mcpError14 } from "@walkeros/core";
 var TITLE14 = "Push Events";
@@ -3416,21 +3404,24 @@ var annotations14 = {
   idempotentHint: false,
   openWorldHint: true
 };
-function createFlowPushToolSpec() {
+function createFlowPushToolSpec(runtime) {
   return {
     name: "flow_push",
     title: TITLE14,
     description: DESCRIPTION12,
     inputSchema: inputSchema12,
     annotations: annotations14,
-    handler: (input) => flowPushHandlerBody(input)
+    handler: (input) => flowPushHandlerBody(runtime, input)
   };
 }
-async function flowPushHandlerBody(input) {
+async function flowPushHandlerBody(runtime, input) {
   const { configPath, event, flow, platform } = input ?? {};
+  if (!runtime.push) {
+    const refusal = unavailableOperation("push");
+    return mcpError14(refusal, refusal.hint);
+  }
   try {
-    const result = await push(configPath, event, {
-      json: true,
+    const result = await runtime.push(configPath, event, {
       flow,
       platform
     });
@@ -3444,12 +3435,15 @@ async function flowPushHandlerBody(input) {
   } catch (error) {
     return mcpError14(
       error,
-      "Check configPath and event format. For web flows, use flow_simulate."
+      refusalHint(
+        error,
+        "Check configPath and event format. For web flows, use flow_simulate."
+      )
     );
   }
 }
-function registerFlowPushTool(server) {
-  const spec = createFlowPushToolSpec();
+function registerFlowPushTool(server, runtime) {
+  const spec = createFlowPushToolSpec(runtime);
   server.registerTool(
     spec.name,
     {
@@ -3468,7 +3462,6 @@ function registerFlowPushTool(server) {
 
 // src/tools/examples.ts
 import { z as z14 } from "zod";
-import { loadJsonConfig as loadJsonConfig2 } from "@walkeros/cli";
 import { fetchPackage, mcpResult as mcpResult15, mcpError as mcpError15 } from "@walkeros/core";
 
 // src/catalog.ts
@@ -3476,7 +3469,7 @@ var NPM_SEARCH_URL = "https://registry.npmjs.org/-/v1/search";
 var JSDELIVR_BASE = "https://cdn.jsdelivr.net/npm";
 var WALKEROS_JSON_PATH = "dist/walkerOS.json";
 var CACHE_TTL = 5 * 60 * 1e3;
-var CLIENT_HEADER = "walkeros-mcp/4.6.0";
+var CLIENT_HEADER = "walkeros-mcp/4.6.1";
 function getPackageBaseUrl() {
   return process.env.WALKEROS_APP_URL || void 0;
 }
@@ -3484,7 +3477,7 @@ var lastFetchInfo;
 function getLastCatalogSource() {
   return lastFetchInfo;
 }
-var cache2 = /* @__PURE__ */ new Map();
+var cache = /* @__PURE__ */ new Map();
 function normalizePlatform(platform) {
   if (platform == null) return [];
   if (typeof platform === "string") {
@@ -3498,7 +3491,7 @@ function normalizePlatform(platform) {
 async function fetchCatalog(filters) {
   const sourceKey = filters?.baseUrl ?? "npm";
   const warnings = [];
-  const cached = cache2.get(sourceKey);
+  const cached = cache.get(sourceKey);
   if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
     lastFetchInfo = {
       source: filters?.baseUrl ? "app" : "npm",
@@ -3556,7 +3549,7 @@ async function fetchCatalog(filters) {
     timestamp: Date.now()
   };
   if (result.entries.length > 0 && result.complete) {
-    cache2.set(sourceKey, { entries: result.entries, timestamp: Date.now() });
+    cache.set(sourceKey, { entries: result.entries, timestamp: Date.now() });
   }
   return { entries: applyFilters(result.entries, filters), warnings };
 }
@@ -3629,10 +3622,13 @@ function applyFilters(entries, filters) {
 }
 
 // src/tools/examples.ts
+var MAX_PACKAGE_LOOKUPS = 25;
 var TITLE15 = "Flow Examples";
-var DESCRIPTION13 = 'List all step examples in a walkerOS flow configuration. Shows example names, step locations, and in/out shapes. Inline examples on a step take precedence; steps without inline examples fall back to the examples shipped by their referenced package. Each result is tagged with its source ("inline" or "package"). Use this to discover available test fixtures and simulation data.';
+var DESCRIPTION13 = 'List all step examples in a walkerOS flow configuration. Shows example names, step locations, and in/out shapes. Inline examples on a step take precedence; steps without inline examples fall back to the examples shipped by their referenced package. Each result is tagged with its source ("inline" or "package"). On the hosted server configPath accepts only inline JSON or a saved flow id (flow_ or cfg_), no file paths or URLs. Use this to discover available test fixtures and simulation data.';
 var inputSchema13 = {
-  configPath: z14.string().min(1).describe("Path to flow configuration file, URL, or inline JSON string"),
+  configPath: z14.string().min(1).describe(
+    "Inline JSON string, file path, or URL of a flow configuration (hosted server: inline JSON or a saved flow id only)"
+  ),
   flow: z14.string().optional().describe("Flow name for multi-flow configs"),
   step: z14.string().optional().describe('Filter to a specific step (e.g., "destination.gtag")'),
   full: z14.boolean().optional().describe(
@@ -3648,20 +3644,20 @@ var annotations15 = {
   idempotentHint: true,
   openWorldHint: false
 };
-function createFlowExamplesToolSpec() {
+function createFlowExamplesToolSpec(runtime) {
   return {
     name: "flow_examples",
     title: TITLE15,
     description: DESCRIPTION13,
     inputSchema: inputSchema13,
     annotations: annotations15,
-    handler: (input) => flowExamplesHandlerBody(input)
+    handler: (input) => flowExamplesHandlerBody(runtime, input)
   };
 }
-async function flowExamplesHandlerBody(input) {
+async function flowExamplesHandlerBody(runtime, input) {
   const { configPath, flow, step, full, includeHidden } = input ?? {};
   try {
-    const rawConfig = await loadJsonConfig2(configPath);
+    const rawConfig = await runtime.load(configPath);
     const flowNames = Object.keys(rawConfig.flows || {});
     const flowName = flow || (flowNames.length === 1 ? flowNames[0] : void 0);
     if (!flowName) {
@@ -3715,6 +3711,19 @@ async function flowExamplesHandlerBody(input) {
       }
       return void 0;
     };
+    const packageLookups = /* @__PURE__ */ new Map();
+    let skippedPackages = false;
+    const examplesForPackage = (packageName) => {
+      const existing = packageLookups.get(packageName);
+      if (existing) return existing;
+      if (packageLookups.size >= MAX_PACKAGE_LOOKUPS) {
+        skippedPackages = true;
+        return Promise.resolve(void 0);
+      }
+      const lookup = loadPackageExamples(packageName);
+      packageLookups.set(packageName, lookup);
+      return lookup;
+    };
     const stepTypes = [
       { key: "sources", type: "source" },
       { key: "transformers", type: "transformer" },
@@ -3731,7 +3740,7 @@ async function flowExamplesHandlerBody(input) {
           continue;
         }
         if (!ref.package) continue;
-        const packageExamples = await loadPackageExamples(ref.package);
+        const packageExamples = await examplesForPackage(ref.package);
         if (packageExamples)
           examples.push(...toItems(packageExamples, type, name, "package"));
       }
@@ -3741,21 +3750,33 @@ async function flowExamplesHandlerBody(input) {
       count: examples.length,
       examples
     };
-    const hints = {
-      next: ["Use flow_simulate with step and event to simulate"]
-    };
+    const warnings = [];
     if (examples.length === 0) {
-      hints.warnings = [
+      warnings.push(
         "No examples found. Add examples to step entries, or reference a package that ships examples (see package_get)."
-      ];
+      );
+    }
+    if (skippedPackages) {
+      warnings.push(
+        `Package examples were looked up for the first ${MAX_PACKAGE_LOOKUPS} packages only. Use step to narrow the result.`
+      );
     }
+    const hints = {
+      next: [
+        runtime.simulate ? "Use flow_simulate with step and event to simulate" : HINT_OUT_OF_PROCESS
+      ],
+      ...warnings.length > 0 ? { warnings } : {}
+    };
     return mcpResult15(result, hints);
   } catch (error) {
-    return mcpError15(error, "Check configPath \u2014 expected a flow.json file");
+    return mcpError15(
+      error,
+      refusalHint(error, "Check configPath \u2014 expected a flow.json file")
+    );
   }
 }
-function registerFlowExamplesTool(server) {
-  const spec = createFlowExamplesToolSpec();
+function registerFlowExamplesTool(server, runtime) {
+  const spec = createFlowExamplesToolSpec(runtime);
   server.registerTool(
     spec.name,
     {
@@ -3774,9 +3795,7 @@ function registerFlowExamplesTool(server) {
 
 // src/tools/flow-load.ts
 import { z as z15 } from "zod";
-import { loadJsonConfig as loadJsonConfig3 } from "@walkeros/cli";
 import { mcpResult as mcpResult16, mcpError as mcpError16 } from "@walkeros/core";
-var API_ID_PREFIX2 = /^(flow|cfg)_/;
 var WEB_SKELETON = {
   version: 4,
   flows: {
@@ -3798,7 +3817,7 @@ var SERVER_SKELETON = {
   }
 };
 var TITLE16 = "Load or Create Flow";
-var DESCRIPTION14 = "Load an existing flow configuration from a local file path, URL, or walkerOS API (by flow ID). Or create a new empty flow by specifying a platform (web or server). Use the add-step prompt to add sources, destinations, transformers, or stores to the flow.";
+var DESCRIPTION14 = "Load an existing flow configuration from a local file path, URL, or walkerOS API (by flow ID). On the hosted server only inline JSON or a saved flow id is accepted, no file paths or URLs. Or create a new empty flow by specifying a platform (web or server). Use the add-step prompt to add sources, destinations, transformers, or stores to the flow.";
 var inputSchema14 = {
   source: z15.string().optional().describe(
     "Flow source: local file path (./flow.json), URL (https://...), inline JSON string, or API flow ID (cfg_...). Omit to create a new flow."
@@ -3817,19 +3836,19 @@ var annotations16 = {
   idempotentHint: true,
   openWorldHint: true
 };
-function createFlowLoadToolSpec(client) {
+function createFlowLoadToolSpec(client, runtime) {
   return {
     name: "flow_load",
     title: TITLE16,
     description: DESCRIPTION14,
     inputSchema: inputSchema14,
     annotations: annotations16,
-    handler: (input) => flowLoadHandlerBody(client, input)
+    handler: (input) => flowLoadHandlerBody(client, runtime, input)
   };
 }
-async function flowLoadHandlerBody(client, input) {
+async function flowLoadHandlerBody(client, runtime, input) {
   const { source, platform } = input ?? {};
-  if (source && API_ID_PREFIX2.test(source)) {
+  if (source && isCloudId(source)) {
     const resolvedProjectId = resolveDefaultProject(client, void 0);
     if (!resolvedProjectId) {
       return mcpError16(new Error(NO_DEFAULT_PROJECT_ERROR));
@@ -3839,9 +3858,8 @@ async function flowLoadHandlerBody(client, input) {
         flowId: source,
         projectId: resolvedProjectId
       });
-      const config = flow.config;
       return mcpResult16(
-        redactNestedStrings(config ?? {}, { skip: keepStructural }),
+        redactNestedStrings(flowConfigOf(flow), { skip: keepStructural }),
         {
           next: ["Use flow_validate to check", "Use add-step prompt to modify"]
         }
@@ -3852,7 +3870,7 @@ async function flowLoadHandlerBody(client, input) {
   }
   try {
     if (source) {
-      const config = await loadJsonConfig3(source);
+      const config = await runtime.load(source);
       return mcpResult16(redactNestedStrings(config, { skip: keepStructural }), {
         next: ["Use flow_validate to check", "Use add-step prompt to modify"]
       });
@@ -3872,14 +3890,15 @@ async function flowLoadHandlerBody(client, input) {
       ]
     });
   } catch (error) {
+    if (error instanceof RuntimeRefusal) return mcpError16(error, error.hint);
     const msg = error instanceof Error ? error.message : "";
     if (msg.includes("not found") || msg.includes("ENOENT"))
       return mcpError16(error, "Check configPath \u2014 expected a flow.json file");
     return mcpError16(error);
   }
 }
-function registerFlowLoadTool(server, client) {
-  const spec = createFlowLoadToolSpec(client);
+function registerFlowLoadTool(server, client, runtime) {
+  const spec = createFlowLoadToolSpec(client, runtime);
   server.registerTool(
     spec.name,
     {
@@ -24517,6 +24536,7 @@ function wrapRegisteredToolsWithTelemetry(server) {
 }
 function createWalkerOSMcpServer(opts) {
   const packageVersion = opts.version ?? "0.0.0";
+  const runtime = opts.runtime ?? createHostedRuntime(opts.client);
   const server = new McpServer(
     {
       name: "walkeros-flow",
@@ -24535,12 +24555,12 @@ function createWalkerOSMcpServer(opts) {
   registerFrameManageTool(server, opts.client);
   registerFeedbackTool(server, opts.client);
   registerDiagnosticsTool(server, opts.client, packageVersion);
-  registerFlowValidateTool(server);
-  registerFlowBundleTool(server, opts.client);
-  registerFlowSimulateTool(server, opts.client);
-  registerFlowPushTool(server);
-  registerFlowExamplesTool(server);
-  registerFlowLoadTool(server, opts.client);
+  registerFlowValidateTool(server, runtime);
+  registerFlowBundleTool(server, opts.client, runtime);
+  registerFlowSimulateTool(server, opts.client, runtime);
+  registerFlowPushTool(server, runtime);
+  registerFlowExamplesTool(server, runtime);
+  registerFlowLoadTool(server, opts.client, runtime);
   registerPackageSearchTool(server);
   registerGetPackageSchemaTool(server);
   registerPackageSchemaResources(server);
@@ -24835,6 +24855,153 @@ function createStreamableHttpHandler(server, opts = {}) {
   };
 }
 
+// src/runtime/local.ts
+import {
+  loadJsonConfig,
+  bundle as bundle2,
+  push,
+  simulateSource,
+  simulateTransformer,
+  simulateCollector,
+  simulateDestination
+} from "@walkeros/cli";
+
+// src/runtime/bundle-cache.ts
+import { createHash } from "crypto";
+import os from "os";
+import path from "path";
+import { mkdir, rm, writeFile } from "fs/promises";
+import { rmSync } from "fs";
+import { bundle } from "@walkeros/cli";
+var MAX_ENTRIES = 8;
+var cache2 = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
+var cleanupRegistered = false;
+function hashConfig(resolvedConfig) {
+  return createHash("sha256").update(resolvedConfig).digest("hex");
+}
+function isInlineJsonConfig(resolvedConfig) {
+  const trimmed = resolvedConfig.trimStart();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return false;
+  try {
+    JSON.parse(resolvedConfig);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function registerProcessCleanup() {
+  if (cleanupRegistered) return;
+  cleanupRegistered = true;
+  const cleanup = () => {
+    for (const entry of cache2.values()) {
+      try {
+        rmSync(entry.dir, { recursive: true, force: true });
+      } catch {
+      }
+    }
+    cache2.clear();
+  };
+  process.once("exit", cleanup);
+}
+async function evictIfNeeded() {
+  while (cache2.size > MAX_ENTRIES) {
+    const oldestKey = cache2.keys().next().value;
+    if (oldestKey === void 0) break;
+    const evicted = cache2.get(oldestKey);
+    cache2.delete(oldestKey);
+    if (evicted) await rm(evicted.dir, { recursive: true, force: true });
+  }
+}
+async function getOrBuildBundle(resolvedConfig) {
+  if (!isInlineJsonConfig(resolvedConfig)) return void 0;
+  registerProcessCleanup();
+  const key = hashConfig(resolvedConfig);
+  const cached = cache2.get(key);
+  if (cached) {
+    cache2.delete(key);
+    cache2.set(key, cached);
+    return cached.bundlePath;
+  }
+  const pending = inFlight.get(key);
+  if (pending) return pending;
+  const build = (async () => {
+    const dir = path.join(
+      os.tmpdir(),
+      `walkeros-mcp-bundle-${key.slice(0, 16)}`
+    );
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    const bundlePath = path.join(dir, "flow.mjs");
+    await writeFile(bundlePath, "", "utf-8");
+    await bundle(resolvedConfig, {
+      target: "simulate",
+      silent: true,
+      buildOverrides: { output: bundlePath, format: "esm", minify: false }
+    });
+    cache2.set(key, { bundlePath, dir });
+    await evictIfNeeded();
+    return bundlePath;
+  })();
+  inFlight.set(key, build);
+  try {
+    return await build;
+  } finally {
+    inFlight.delete(key);
+  }
+}
+
+// src/runtime/local.ts
+function createLocalRuntime() {
+  return {
+    load: (input) => loadJsonConfig(input),
+    bundle: (input, opts) => bundle2(input, {
+      flowName: opts.flowName,
+      stats: opts.stats,
+      buildOverrides: opts.output ? { output: opts.output } : void 0
+    }),
+    async simulate(input, opts) {
+      let bundlePath;
+      try {
+        bundlePath = await getOrBuildBundle(input);
+      } catch {
+        bundlePath = void 0;
+      }
+      const common = { bundlePath, flow: opts.flow, silent: true };
+      switch (opts.stepType) {
+        case "source":
+          return simulateSource(input, opts.event, {
+            sourceId: opts.stepId,
+            ...common
+          });
+        case "transformer":
+          return simulateTransformer(
+            input,
+            opts.event,
+            { transformerId: opts.stepId, ...common, ingest: opts.ingest }
+          );
+        case "collector":
+          return simulateCollector(
+            input,
+            opts.event,
+            { collectorName: opts.stepId, ...common, state: opts.state }
+          );
+        case "destination":
+          return simulateDestination(
+            input,
+            opts.event,
+            { destinationId: opts.stepId, ...common }
+          );
+      }
+    },
+    push: (input, event, opts) => push(input, event, {
+      json: true,
+      flow: opts.flow,
+      platform: opts.platform
+    })
+  };
+}
+
 // src/tool-definitions.ts
 import { z as z20 } from "zod";
 import { schemas as schemas6 } from "@walkeros/cli/dev";
@@ -24999,7 +25166,7 @@ var TOOL_DEFINITIONS = [
   {
     name: "flow_validate",
     title: "Validate Flow",
-    description: "Validate walkerOS events, flow configurations, mapping rules, or data contracts. Accepts JSON strings, file paths, or URLs as input. Returns validation results with errors, warnings, and details.",
+    description: "Validate walkerOS events, flow configurations, mapping rules, or data contracts. Accepts JSON strings, file paths, or URLs as input; on the hosted server only inline JSON or a saved flow id (flow_ or cfg_), no file paths or URLs. Returns validation results with errors, warnings, and details.",
     inputSchema: schemas6.ValidateInputShape,
     annotations: {
       readOnlyHint: true,
@@ -25037,10 +25204,11 @@ var TOOL_DEFINITIONS = [
       verbose: z20.boolean().optional()
     },
     annotations: {
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false
+      // Not read-only: simulation compiles and runs the flow in process.
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
     }
   },
   {
@@ -25063,7 +25231,7 @@ var TOOL_DEFINITIONS = [
   {
     name: "flow_examples",
     title: "Flow Examples",
-    description: "List all step examples in a walkerOS flow configuration. Shows example names, step locations, and in/out shapes. Use this to discover available test fixtures and simulation data.",
+    description: "List all step examples in a walkerOS flow configuration. Shows example names, step locations, and in/out shapes. On the hosted server configPath accepts only inline JSON or a saved flow id (flow_ or cfg_), no file paths or URLs. Use this to discover available test fixtures and simulation data.",
     inputSchema: {
       configPath: z20.string().min(1),
       flow: z20.string().optional(),
@@ -25081,7 +25249,7 @@ var TOOL_DEFINITIONS = [
   {
     name: "flow_load",
     title: "Load or Create Flow",
-    description: "Load an existing flow configuration from a local file path, URL, or walkerOS API (by flow ID). Or create a new empty flow by specifying a platform (web or server). Use the add-step prompt to add sources, destinations, transformers, or stores to the flow.",
+    description: "Load an existing flow configuration from a local file path, URL, or walkerOS API (by flow ID). On the hosted server only inline JSON or a saved flow id is accepted, no file paths or URLs. Or create a new empty flow by specifying a platform (web or server). Use the add-step prompt to add sources, destinations, transformers, or stores to the flow.",
     inputSchema: {
       source: z20.string().optional(),
       platform: z20.enum(["web", "server"]).optional()
@@ -25172,7 +25340,7 @@ var TOOL_DEFINITIONS = [
 ];
 
 // src/index.ts
-function createToolHandlers(client, packageVersion = "0.0.0") {
+function createToolHandlers(client, packageVersion = "0.0.0", runtime = createHostedRuntime(client)) {
   const specs = [
     createAuthToolSpec(client),
     createProjectManageToolSpec(client),
@@ -25184,12 +25352,12 @@ function createToolHandlers(client, packageVersion = "0.0.0") {
     createHubManageToolSpec(client),
     createFrameManageToolSpec(client),
     createFeedbackToolSpec(client),
-    createFlowValidateToolSpec(),
-    createFlowBundleToolSpec(client),
-    createFlowSimulateToolSpec(client),
-    createFlowPushToolSpec(),
-    createFlowExamplesToolSpec(),
-    createFlowLoadToolSpec(client),
+    createFlowValidateToolSpec(runtime),
+    createFlowBundleToolSpec(client, runtime),
+    createFlowSimulateToolSpec(client, runtime),
+    createFlowPushToolSpec(runtime),
+    createFlowExamplesToolSpec(runtime),
+    createFlowLoadToolSpec(client, runtime),
     createPackageSearchToolSpec(),
     createPackageGetToolSpec(),
     createDiagnosticsToolSpec(client, packageVersion)
@@ -25249,7 +25417,10 @@ export {
   HUB_NOT_FOUND_HINT,
   HttpToolClient,
   DESCRIPTION7 as OBSERVE_SESSION_DESCRIPTION,
+  RuntimeRefusal,
   TOOL_DEFINITIONS,
+  createHostedRuntime,
+  createLocalRuntime,
   createStreamableHttpHandler,
   createToolHandlers,
   createWalkerOSMcpServer,