@walkeros/mcp 4.6.0 → 4.6.1

package/dist/stdio.js

@@ -8,7 +8,7 @@ import { setClientContext } from "@walkeros/cli";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/tools/validate.ts
-import { validate, loadJsonConfig } from "@walkeros/cli";
+import { validate } from "@walkeros/cli";
 import { schemas } from "@walkeros/cli/dev";
 import { mcpResult, mcpError } from "@walkeros/core";
 
@@ -102,7 +102,54 @@ var ExamplesListOutputShape = {
   ).describe("Step examples")
 };
 
+// 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/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/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 = [];
@@ -132,7 +179,7 @@ function detectDeprecatedStorePackages(config) {
   return errors;
 }
 var TITLE = "Validate Flow";
-var 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.";
+var 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.";
 var inputSchema = schemas.ValidateInputShape;
 var annotations = {
   readOnlyHint: true,
@@ -140,17 +187,17 @@ var annotations = {
   idempotentHint: true,
   openWorldHint: false
 };
-function createFlowValidateToolSpec() {
+function createFlowValidateToolSpec(runtime) {
   return {
     name: "flow_validate",
     title: TITLE,
     description: DESCRIPTION,
     inputSchema,
     annotations,
-    handler: (input) => flowValidateHandlerBody(input)
+    handler: (input) => flowValidateHandlerBody(runtime, input)
   };
 }
-async function flowValidateHandlerBody(input) {
+async function flowValidateHandlerBody(runtime, input) {
   const {
     type,
     input: validateInput,
@@ -158,30 +205,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",
@@ -192,12 +236,15 @@ async function flowValidateHandlerBody(input) {
   } catch (error) {
     return mcpError(
       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,
     {
@@ -215,17 +262,14 @@ function registerFlowValidateTool(server) {
 }
 
 // src/tools/bundle.ts
-import { bundle } from "@walkeros/cli";
 import { schemas as schemas2 } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult2, mcpError as mcpError2 } 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
@@ -240,24 +284,28 @@ var annotations2 = {
   idempotentHint: false,
   openWorldHint: true
 };
-function createFlowBundleToolSpec(client) {
+function createFlowBundleToolSpec(client, runtime) {
   return {
     name: "flow_bundle",
     title: TITLE2,
     description: DESCRIPTION2,
     inputSchema: inputSchema2,
     annotations: annotations2,
-    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 mcpError2(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 mcpResult2(
@@ -281,11 +329,14 @@ async function flowBundleHandlerBody(client, input) {
       }
     );
   } catch (error) {
-    return mcpError2(error, "Run flow_validate for detailed error messages");
+    return mcpError2(
+      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,
     {
@@ -304,101 +355,17 @@ function registerFlowBundleTool(server, client) {
 
 // src/tools/simulate.ts
 import { z as z2 } from "zod";
-import {
-  simulateSource,
-  simulateTransformer,
-  simulateDestination,
-  simulateCollector
-} from "@walkeros/cli";
 import { schemas as schemas3 } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult3, mcpError as mcpError3 } 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 TITLE3 = "Simulate Flow";
 var DESCRIPTION3 = '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 inputSchema3 = {
@@ -427,23 +394,31 @@ var inputSchema3 = {
   )
 };
 var annotations3 = {
-  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: TITLE3,
     description: DESCRIPTION3,
     inputSchema: inputSchema3,
     annotations: annotations3,
-    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 mcpError3(refusal, refusal.hint);
+  }
   try {
     if (!event) {
       throw new Error(
@@ -473,66 +448,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") {
@@ -620,11 +545,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 mcpError3(error, hint);
+    return mcpError3(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,
     {
@@ -643,7 +568,6 @@ function registerFlowSimulateTool(server, client) {
 
 // src/tools/push.ts
 import { z as z3 } from "zod";
-import { push } from "@walkeros/cli";
 import { schemas as schemas4 } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult4, mcpError as mcpError4 } from "@walkeros/core";
 var TITLE4 = "Push Events";
@@ -662,21 +586,24 @@ var annotations4 = {
   idempotentHint: false,
   openWorldHint: true
 };
-function createFlowPushToolSpec() {
+function createFlowPushToolSpec(runtime) {
   return {
     name: "flow_push",
     title: TITLE4,
     description: DESCRIPTION4,
     inputSchema: inputSchema4,
     annotations: annotations4,
-    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 mcpError4(refusal, refusal.hint);
+  }
   try {
-    const result = await push(configPath, event, {
-      json: true,
+    const result = await runtime.push(configPath, event, {
       flow,
       platform
     });
@@ -690,12 +617,15 @@ async function flowPushHandlerBody(input) {
   } catch (error) {
     return mcpError4(
       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,
     {
@@ -714,7 +644,6 @@ function registerFlowPushTool(server) {
 
 // src/tools/examples.ts
 import { z as z4 } from "zod";
-import { loadJsonConfig as loadJsonConfig2 } from "@walkeros/cli";
 import { fetchPackage, mcpResult as mcpResult5, mcpError as mcpError5 } from "@walkeros/core";
 
 // src/catalog.ts
@@ -722,7 +651,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;
 }
@@ -730,7 +659,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") {
@@ -744,7 +673,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",
@@ -802,7 +731,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 };
 }
@@ -875,10 +804,13 @@ function applyFilters(entries, filters) {
 }
 
 // src/tools/examples.ts
+var MAX_PACKAGE_LOOKUPS = 25;
 var TITLE5 = "Flow Examples";
-var DESCRIPTION5 = '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 DESCRIPTION5 = '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 inputSchema5 = {
-  configPath: z4.string().min(1).describe("Path to flow configuration file, URL, or inline JSON string"),
+  configPath: z4.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: z4.string().optional().describe("Flow name for multi-flow configs"),
   step: z4.string().optional().describe('Filter to a specific step (e.g., "destination.gtag")'),
   full: z4.boolean().optional().describe(
@@ -894,20 +826,20 @@ var annotations5 = {
   idempotentHint: true,
   openWorldHint: false
 };
-function createFlowExamplesToolSpec() {
+function createFlowExamplesToolSpec(runtime) {
   return {
     name: "flow_examples",
     title: TITLE5,
     description: DESCRIPTION5,
     inputSchema: inputSchema5,
     annotations: annotations5,
-    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) {
@@ -961,6 +893,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" },
@@ -977,7 +922,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"));
       }
@@ -987,21 +932,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 mcpResult5(result, hints);
   } catch (error) {
-    return mcpError5(error, "Check configPath \u2014 expected a flow.json file");
+    return mcpError5(
+      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,
     {
@@ -1212,7 +1169,6 @@ function registerGetPackageSchemaTool(server) {
 
 // src/tools/flow-load.ts
 import { z as z6 } from "zod";
-import { loadJsonConfig as loadJsonConfig3 } from "@walkeros/cli";
 import { mcpResult as mcpResult7, mcpError as mcpError7 } from "@walkeros/core";
 
 // src/types.ts
@@ -1297,7 +1253,6 @@ function resolveDefaultProject(client, projectId) {
 }
 
 // src/tools/flow-load.ts
-var API_ID_PREFIX2 = /^(flow|cfg)_/;
 var WEB_SKELETON = {
   version: 4,
   flows: {
@@ -1319,7 +1274,7 @@ var SERVER_SKELETON = {
   }
 };
 var TITLE6 = "Load or Create Flow";
-var DESCRIPTION6 = "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 DESCRIPTION6 = "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 inputSchema6 = {
   source: z6.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."
@@ -1338,19 +1293,19 @@ var annotations6 = {
   idempotentHint: true,
   openWorldHint: true
 };
-function createFlowLoadToolSpec(client) {
+function createFlowLoadToolSpec(client, runtime) {
   return {
     name: "flow_load",
     title: TITLE6,
     description: DESCRIPTION6,
     inputSchema: inputSchema6,
     annotations: annotations6,
-    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 mcpError7(new Error(NO_DEFAULT_PROJECT_ERROR));
@@ -1360,9 +1315,8 @@ async function flowLoadHandlerBody(client, input) {
         flowId: source,
         projectId: resolvedProjectId
       });
-      const config = flow.config;
       return mcpResult7(
-        redactNestedStrings(config ?? {}, { skip: keepStructural }),
+        redactNestedStrings(flowConfigOf(flow), { skip: keepStructural }),
         {
           next: ["Use flow_validate to check", "Use add-step prompt to modify"]
         }
@@ -1373,7 +1327,7 @@ async function flowLoadHandlerBody(client, input) {
   }
   try {
     if (source) {
-      const config = await loadJsonConfig3(source);
+      const config = await runtime.load(source);
       return mcpResult7(redactNestedStrings(config, { skip: keepStructural }), {
         next: ["Use flow_validate to check", "Use add-step prompt to modify"]
       });
@@ -1393,14 +1347,15 @@ async function flowLoadHandlerBody(client, input) {
       ]
     });
   } catch (error) {
+    if (error instanceof RuntimeRefusal) return mcpError7(error, error.hint);
     const msg = error instanceof Error ? error.message : "";
     if (msg.includes("not found") || msg.includes("ENOENT"))
       return mcpError7(error, "Check configPath \u2014 expected a flow.json file");
     return mcpError7(error);
   }
 }
-function registerFlowLoadTool(server, client) {
-  const spec = createFlowLoadToolSpec(client);
+function registerFlowLoadTool(server, client, runtime) {
+  const spec = createFlowLoadToolSpec(client, runtime);
   server.registerTool(
     spec.name,
     {
@@ -1466,7 +1421,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 mcpResult8({ ok: true });
   } catch (error) {
@@ -24491,6 +24446,70 @@ async function createMcpEmitter(opts) {
   };
 }
 
+// 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/server.ts
 var currentEmitter;
 function getMcpEmitterSingleton() {
@@ -24525,6 +24544,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",
@@ -24543,12 +24563,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);
@@ -24822,8 +24842,155 @@ var HttpToolClient = class {
   }
 };
 
+// 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/stdio.ts
-setClientContext({ type: "mcp", version: "4.6.0" });
+setClientContext({ type: "mcp", version: "4.6.1" });
 process.on("uncaughtException", (err) => {
   const emitter = getMcpEmitterSingleton();
   if (emitter) {
@@ -24843,7 +25010,8 @@ process.on("unhandledRejection", (reason) => {
 async function main() {
   const server = createWalkerOSMcpServer({
     client: new HttpToolClient(),
-    version: "4.6.0"
+    version: "4.6.1",
+    runtime: createLocalRuntime()
   });
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -24853,7 +25021,7 @@ main().catch(async (error) => {
   try {
     const emitter = await createMcpEmitter({
       clientInfo: void 0,
-      packageVersion: "4.6.0"
+      packageVersion: "4.6.1"
     });
     await emitter.emitError("startup");
   } catch {