@walkeros/mcp 4.6.0 → 4.7.0-next-1790187973605

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";
@@ -1929,7 +2024,7 @@ var HUB_MANAGE_INPUT_SCHEMA = {
     'One frame (frm_...), the named rectangle a note hangs on. Action "knowledge" only. Narrower than pageKey, since a page holds several frames.'
   ),
   markId: z8.string().min(1).max(MAX_MARK_ID_LENGTH).optional().describe(
-    'One mark within "frameId". Action "knowledge" only, and refused without frameId, since a mark id alone addresses nothing. Naming a mark is also what attaches the message bodies.'
+    'One tag within "frameId", by its tag id (the id of an entry in frame_manage marks.tags). Action "knowledge" only, and refused without frameId, since a mark id alone addresses nothing. Naming a mark is also what attaches the message bodies.'
   )
 };
 var annotations8 = {
@@ -2465,7 +2560,7 @@ import { mcpResult as mcpResult9, mcpError as mcpError9 } from "@walkeros/core";
 var FRAME_ID_PATTERN2 = /^frm_[A-Za-z0-9_-]{21}$/;
 var MAX_PAGE_KEY_CHARS = 1024;
 var TITLE9 = "Frames";
-var FRAME_MANAGE_DESCRIPTION = 'Read the frames of a measurement plan: named rectangles with marks inside them, drawn in Tag Mode or in the app. Actions: list (every frame of the project, without marks), page (the frames of one page at any depth, with marks), get (one frame with its marks). Read-only: frames are drawn and edited in Tag Mode or the app, never here. A frame name is documentation; the marks inside it carry the meaning. A frame that extends another stores only what it adds. Use hub_manage action "knowledge" with a frameId or markId to read what people wrote on a frame. A markId is an id read from the marks of a frame here: mark ids come back literal so they can be passed straight back, while the text around them is wrapped as data. An entity action is an object carrying its id beside the raw attribute text, because the id is the address and the raw text is not.';
+var FRAME_MANAGE_DESCRIPTION = 'Read the frames of a measurement plan: named rectangles with marks inside them, drawn in Tag Mode or in the app. Actions: list (every frame of the project, without marks), page (the frames of one page at any depth, with marks), get (one frame with its marks). Read-only: frames are drawn and edited in Tag Mode or the app, never here. A frame name is documentation; the marks inside it carry the meaning. A frame that extends another stores only what it adds, so its tags may carry only the fields they change. Marks are { tags, note }: tags is one flat list of tags, each with an id, a kind such as entity, property or action, a name, and a parentId naming the tag it sits under; note is the frame\u2019s own description and thread. Use hub_manage action "knowledge" with a frameId or markId to read what people wrote on a frame. A markId is a tag id: a tag\u2019s id, parentId and threadRef come back literal when they have the shape the app mints, so they can be passed straight back; every other string value in the marks is wrapped as data, and so is an object key that is not a plain identifier.';
 var FRAME_MANAGE_INPUT_SCHEMA = {
   action: z9.enum(["list", "page", "get"]).describe(
     "list the project\u2019s frames, read one page with marks, or read one frame"
@@ -2489,8 +2584,8 @@ var annotations9 = {
 var FRAME_HINT_OPEN_PAGE_OR_GET = 'Use action "page" with a pageKey (a frame\u2019s source.key) to read a page with marks, or action "get" with a frameId.';
 var FRAME_HINT_NAMES_ARE_DOCUMENTATION = "Frame names are documentation; the marks inside a frame carry the meaning.";
 var FRAME_HINT_NONE_YET = "This project has no frames yet. Frames are drawn in Tag Mode or the app, not through this tool.";
-var FRAME_HINT_MARK_SPACE = "Marks are in their frame\u2019s own 0..1 space; a child frame sits inside its parent through placements[].rect.";
-var FRAME_HINT_READ_KNOWLEDGE = 'Use hub_manage action "knowledge" with frameId (and markId) to read what people wrote here. A markId is an id from these marks, and an entity action is addressed by its own id, never by its raw text.';
+var FRAME_HINT_MARK_SPACE = "Tag geometry is fractional: a rect is 0..1 of its frame, and an at is 0..1 of its parent tag\u2019s box, or of the frame for a root tag; a child frame sits inside its parent through placements[].rect.";
+var FRAME_HINT_READ_KNOWLEDGE = 'Use hub_manage action "knowledge" with frameId (and markId) to read what people wrote here. A markId is a tag id from these marks, and a tag\u2019s threadRef is the id of its thread entry there.';
 var FRAME_HINT_NONE_ON_PAGE = 'No frames on this page. Check the pageKey against the source.key values from action "list".';
 var FRAME_HINT_EXTENDS_BASE = "This frame extends another and stores only what it adds; read the base frame (extends) for the rest.";
 var FRAME_NOT_FOUND_HINT = 'Use action "list" or "page" to find frame ids.';
@@ -2526,67 +2621,59 @@ function serializeLean(frame) {
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function actionMarkId(entityId, raw) {
-  return `${entityId}#action.${raw}`;
-}
-var MARK_ADDRESS_KEYS = /* @__PURE__ */ new Set([
-  // The mark id itself, and a component of the data and action addresses.
-  "id",
-  // The first half of an ambient address, `ambient.<kind>.<key>`, and the
-  // discriminator a reader branches on.
-  "kind",
-  // An entity's pointer at another entity, which is that entity's mark id.
-  "link",
-  // The thread a note became, which action "note_add" takes as threadId.
-  "threadRef"
+var TAG_ID_PATTERN = /^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*(?:#(?:data\.v?[0-9]+|action\.[0-9]+|context\.[0-9]+|[0-9]+))?$/;
+var MAX_TAG_ID_CHARS = 200;
+var THREAD_ID_PATTERN = /^thr_[a-z0-9]{21}$/;
+var isTagId = (value) => value.length <= MAX_TAG_ID_CHARS && TAG_ID_PATTERN.test(value);
+var isThreadId = (value) => THREAD_ID_PATTERN.test(value);
+var TAG_ADDRESSES = /* @__PURE__ */ new Map([
+  // The tag id: the markId `hub_manage` action "knowledge" takes, which the
+  // app joins to the frame id as the anchor key `<frameId>:<markId>`.
+  ["id", isTagId],
+  // The tag this one sits under, which is that tag's id: the only relation
+  // between tags, so a reader joins it to `id` to rebuild the tree, and it is
+  // a markId in its own right.
+  ["parentId", isTagId],
+  // The hub thread this tag's note thread became: the `id` of the thread
+  // entry `hub_manage` action "knowledge" returns for this tag.
+  ["threadRef", isThreadId]
 ]);
-var MARK_ADDRESS_LIST_KEYS = /* @__PURE__ */ new Set([
-  // The entities a context band covers, by their mark ids.
-  "covers"
-]);
-var MARK_PAGE_DATA_KEYS = /* @__PURE__ */ new Set(["anchor", "actionAnchors"]);
-function isProseKeyedRecord(key, owner) {
-  return key === "data" && typeof owner.kind !== "string";
-}
-function walkMarks(value, inPageData = false) {
+var NOTE_ADDRESSES = /* @__PURE__ */ new Map(
+  [["threadRef", isThreadId]]
+);
+var MARK_KEY_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$-]{0,63}$/;
+var markKey = (key) => MARK_KEY_PATTERN.test(key) ? key : wrapUserData(key);
+function walkText(value) {
   if (typeof value === "string") return wrapUserData(value);
-  if (Array.isArray(value)) {
-    return value.map((item) => walkMarks(item, inPageData));
-  }
+  if (Array.isArray(value)) return value.map(walkText);
   if (!isRecord2(value)) return value;
-  const entityId = typeof value.id === "string" ? value.id : void 0;
   const out = {};
   for (const [key, child] of Object.entries(value)) {
-    if (MARK_PAGE_DATA_KEYS.has(key)) {
-      out[key] = walkMarks(child, true);
-    } else if (!inPageData && isRecord2(child) && isProseKeyedRecord(key, value)) {
-      out[key] = proseKeyedPairs(child);
+    out[markKey(key)] = walkText(child);
+  }
+  return out;
+}
+function walkMarks(marks) {
+  const out = {};
+  for (const [key, value] of Object.entries(marks)) {
+    if (key === "tags" && Array.isArray(value)) {
+      out[key] = value.map((tag) => walkAddressed(tag, TAG_ADDRESSES));
+    } else if (key === "note") {
+      out[key] = walkAddressed(value, NOTE_ADDRESSES);
     } else {
-      out[key] = walkMarkEntry(key, child, entityId, inPageData);
+      out[markKey(key)] = walkText(value);
     }
   }
   return out;
 }
-function proseKeyedPairs(record) {
-  return Object.entries(record).map(([key, value]) => ({
-    key: wrapUserData(key),
-    value: walkMarks(value)
-  }));
-}
-function walkMarkEntry(key, child, entityId, inPageData) {
-  if (inPageData) return walkMarks(child, true);
-  if (MARK_ADDRESS_KEYS.has(key) && typeof child === "string") return child;
-  if (MARK_ADDRESS_LIST_KEYS.has(key) && Array.isArray(child)) {
-    return child.map(
-      (item) => typeof item === "string" ? item : walkMarks(item)
-    );
-  }
-  if (key === "actions" && entityId !== void 0 && Array.isArray(child)) {
-    return child.map(
-      (raw) => typeof raw === "string" ? { id: actionMarkId(entityId, raw), raw: wrapUserData(raw) } : walkMarks(raw)
-    );
+function walkAddressed(value, addresses) {
+  if (!isRecord2(value)) return walkText(value);
+  const out = {};
+  for (const [key, field] of Object.entries(value)) {
+    const isAddress = addresses.get(key);
+    out[markKey(key)] = isAddress !== void 0 && typeof field === "string" && isAddress(field) ? field : walkText(field);
   }
-  return walkMarks(child);
+  return out;
 }
 function serializeFrame(frame) {
   return {
@@ -2738,7 +2825,7 @@ async function feedbackHandlerBody(client, input) {
     const isAnonymous = explicitAnonymous ?? anonymous ?? true;
     await client.submitFeedback(text, {
       anonymous: isAnonymous,
-      version: "4.6.0"
+      version: "4.7.0-next-1790187973605"
     });
     return mcpResult10({ ok: true });
   } catch (error) {
@@ -2762,7 +2849,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 +2944,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 +2989,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 +2997,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 +3015,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 +3046,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 +3072,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 +3094,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 +3139,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 +3165,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 = {
@@ -3165,7 +3188,7 @@ var inputSchema11 = {
   // Override the (optional) CLI `step` shape: the simulate handler hard-requires
   // a target step (no all-steps mode), so the registered schema must be honest.
   step: z12.string().describe(
-    'Required. Target step as "type.name" \u2014 e.g. "source.demo", "destination.gtag", "transformer.router".'
+    'Required. Target step as "type.name", e.g. "source.demo", "collector.default", "destination.gtag", "transformer.router". A collector step runs enrichment and then collector.next, returning every event the destinations would receive (none after a stop).'
   ),
   verbose: z12.boolean().optional().describe("Include full payload per destination (default: false)"),
   ingest: z12.record(z12.string(), z12.unknown()).optional().describe(
@@ -3181,23 +3204,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 +3258,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 +3355,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 +3378,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 +3396,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 +3427,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 +3454,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 +3461,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.7.0-next-1790187973605";
 function getPackageBaseUrl() {
   return process.env.WALKEROS_APP_URL || void 0;
 }
@@ -3484,7 +3469,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 +3483,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 +3541,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 +3614,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 +3636,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 +3703,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 +3732,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 +3742,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 +3787,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 +3809,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 +3828,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 +3850,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 +3862,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 +3882,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,
     {
@@ -24264,9 +24275,10 @@ function registerAddStepPrompt(server) {
               "",
               "Important:",
               "- Read the walkeros://reference/flow-schema resource to understand connection rules.",
-              "- Sources connect to pre-collector transformers via `next`.",
-              "- Destinations connect to post-collector transformers via `before`.",
-              '- Routing supports string IDs, sequences (`["a", "b"]`), or RouteConfig (`{ match?, next }` for gated single-target or `{ match?, one: [...] }` for first-match dispatch). Use `many` (instead of `one`) when every matching entry should run as an independent parallel flow \u2014 restricted to pre-collector positions. Omit `match` for always-match.',
+              "- Sources connect to transformers via `next` (runs before the collector).",
+              "- The collector connects to transformers via `collector.next` (runs once per event before the destination fan-out, for every destination).",
+              "- Destinations connect to transformers via `before` (runs for that destination only; put per-destination filtering here).",
+              '- Routing uses one grammar in every chain field: string IDs, sequences (`["a", "b"]`, where a member\'s own `next` runs right after it), or RouteConfig (`{ match?, next }` for a gated link, `{ match?, one: [...] }` for first-match dispatch, `{ match?, many: [...] }` to fork each match into its own copy that finishes the rest of the path, `{ match?, stop: true }` to drop). A `stop` in `collector.next` drops the event for all destinations. Omit `match` for always-match.',
               "- A transformer entry can be code-bearing (`code`), package-bearing (`package`), or a **pass-through step** (no `code`, no `package`). Pass-through synthesis is automatic at runtime. Three flavors of pass-through: `before`/`next`-only (named hop reusable across destinations), `cache`-only (dedup, rate-limit), or `mapping`-only (declarative event-to-event transform). A pass-through must declare at least one of `before`, `next`, `cache`, or `mapping`.",
               "- The `mapping` field on a transformer step uses the same `Mapping.Config` shape as destinations, but the semantic is event-to-event (mutates the event in place via `policy`, per-rule `policy`, `mapping[].name` for renames, `mapping[].ignore` to drop). Vendor-payload fields (`data`, `silent`) are no-ops at this position.",
               "- Closed schema: unknown top-level keys on a transformer step are errors (catches typos like `dedup` instead of `cache`). `code` + `package` together is a conflict.",
@@ -24405,7 +24417,7 @@ var SERVER_INSTRUCTIONS = `walkerOS is an open-source, privacy-first event data
 
 ## Architecture: Source \u2192 Collector \u2192 Destination(s)
 
-Every component in a flow is a **step**: sources capture events, transformers process them, destinations deliver them, stores provide shared state. Steps connect via \`next\` (pre-collector) and \`before\` (post-collector) chains.
+Every component in a flow is a **step**: sources capture events, transformers process them, destinations deliver them, stores provide shared state. Steps connect via chains: \`source.next\` runs before the collector, \`collector.next\` runs once per event before the destination fan-out (all destinations), and \`destination.before\` runs for one destination.
 
 ## Flow Config Structure
 
@@ -24433,11 +24445,11 @@ Every component in a flow is a **step**: sources capture events, transformers pr
 - **Contracts** define event schemas using entity-action keying. Can generate FROM mappings or scaffold mappings FROM contracts.
 - **Variables** ($var, $env, $secret, $code, $store) enable DRY, environment-aware config. \`$var.name\` is a reusable flow variable from the top-level \`variables\` block; whole-string refs preserve native type (object/array/scalar), inline interpolation requires a scalar, deep paths via \`$var.name.deep.path\`. \`$env.NAME[:default]\` is an environment variable resolved at bundle/deploy time (non-secret config only). \`$secret.NAME\` is a managed secret the deploy pipeline injects into the server runner at runtime; credentials, tokens, and private keys must use \`$secret\`, not \`$env\`.
 - **Consent** gates destinations, mapping rules, and individual fields. Privacy-first by design.
-- **Routing** wires steps via \`next\` (pre-collector) and \`before\` (post-collector). A route is a string ID, a sequence (\`["a", "b"]\`), or a RouteConfig (\`{ match?, next }\` or \`{ match?, one: [...] }\`). The \`one\` operator dispatches first-match against an ordered list of branches. Use \`many\` (instead of \`one\`) when every matching entry should run as an independent parallel flow \u2014 restricted to pre-collector positions. The optional \`match\` field is omitted to mean always-match (no wildcard literal).
+- **Routing** uses one grammar in every chain field (\`source.before\`, \`source.next\`, \`transformer.before\`, \`transformer.next\`, \`collector.next\`, \`destination.before\`, \`destination.next\`). A route is a string ID, a sequence (\`["a", "b"]\`), or a RouteConfig: \`{ match?, next }\`, \`{ match?, one: [...] }\` (first match wins), \`{ match?, many: [...] }\` (every match becomes its own copy of the event with its own id and finishes the rest of the path on its own, never merged), or \`{ match?, stop: true }\` (ends that copy). In a sequence, a member's own \`next\` runs right after it, then the sequence continues. \`match\` reads \`{ ingest, event }\` and each route is evaluated when the event reaches it. A \`stop\` in \`collector.next\` drops the event for every destination; per-destination filtering belongs in \`destination.before\`. An array of only route configs is an implicit \`one\`. The optional \`match\` field is omitted to mean always-match (no wildcard literal).
 - **Pass-through steps** are transformer entries with no \`code\` and no \`package\`. The runtime synthesizes the push for them automatically. Three flavors share this shape: a \`before\` / \`next\`-only step (named hop reusable across destinations), a \`cache\`-only step (dedup, rate-limit), and a \`mapping\`-only step (declarative event-to-event transform). A pass-through must declare at least one of \`before\`, \`next\`, \`cache\`, or \`mapping\`.
 - **Mapping at the transformer position** uses the same \`Mapping.Config\` shape as destinations, but the semantic is event-to-event: \`policy\` and per-rule \`policy\`, \`mapping[].name\` (rename), \`mapping[].ignore\` (drop from chain), \`consent\`, and \`include\` apply. Vendor-payload fields (\`data\`, \`silent\`, \`mapping[].data\`) are no-ops at this position.
 - **Closed-schema rule on transformer entries:** known keys only. Operative keys are \`code\`, \`package\`, \`before\`, \`next\`, \`cache\`, \`mapping\`. Combined with structural keys (\`config\`, \`env\`, \`validate\`, \`disabled\`, \`id\`, etc.). Unknown top-level keys on a transformer step are errors (catches typos like \`dedup: {}\` instead of nested under \`cache\`). \`code\` + \`package\` together is a conflict.
-- **Cache** memoizes step output on a configured store. Set \`cache.stop: true\` to short-circuit the chain on HIT (sources default to stop-on-HIT). Set \`cache.namespace\` to prefix keys; omit it to write keys directly. \`CacheRule.match\` is optional, omit for always-match.
+- **Cache** memoizes step output on a configured store. Set \`cache.stop: true\` to short-circuit the chain on HIT (sources default to stop-on-HIT); in a source chain or \`collector.next\` that halts the event for all destinations. Set \`cache.namespace\` to prefix keys; omit it to write keys directly. \`CacheRule.match\` is optional, omit for always-match.
 
 ## Simulation Tips
 
@@ -24517,6 +24529,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 +24548,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 +24848,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 +25159,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 +25197,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 +25224,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 +25242,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 +25333,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 +25345,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 +25410,10 @@ export {
   HUB_NOT_FOUND_HINT,
   HttpToolClient,
   DESCRIPTION7 as OBSERVE_SESSION_DESCRIPTION,
+  RuntimeRefusal,
   TOOL_DEFINITIONS,
+  createHostedRuntime,
+  createLocalRuntime,
   createStreamableHttpHandler,
   createToolHandlers,
   createWalkerOSMcpServer,