@walkeros/mcp 4.3.1 → 4.3.2

package/dist/index.js

@@ -571,6 +571,7 @@ var PREVIEW_SUMMARY_FIELDS = [
   "grant",
   "sessionGrant",
   "sessionExpiresAt",
+  "sessionId",
   "status",
   "observeFeed",
   "createdBy",
@@ -594,6 +595,18 @@ function redactPreviewList(data) {
     ...data.total !== void 0 ? { total: data.total } : {}
   };
 }
+async function resolveLiveSessionId(client, flowId, projectId) {
+  try {
+    const result = await client.listJourneys({
+      flowId,
+      ...projectId !== void 0 && { projectId },
+      limit: 1
+    });
+    return result.sessionId;
+  } catch {
+    return null;
+  }
+}
 function createFlowManageToolSpec(client) {
   return {
     name: "flow_manage",
@@ -845,16 +858,17 @@ async function flowManageHandlerBody(client, input) {
             new Error("preview_regrant is not supported by this client")
           );
         }
+        const pairedSessionId = sessionId ?? await resolveLiveSessionId(client, flowId, resolvedProjectId);
         const data = await client.regrantPreview({
           projectId: resolvedProjectId,
           flowId,
           previewId,
           origins: origins ?? [],
-          ...sessionId ? { sessionId } : {}
+          ...pairedSessionId ? { sessionId: pairedSessionId } : {}
         });
         return mcpResult3(redactPreview(data), {
           next: [
-            sessionId ? "Open activationUrl on the target origin: it activates the web preview AND forwards its events to the observe session. Use sessionGrant as the X-Walkeros-Preview header for direct server-hop test events." : "Open activationUrl on the target origin to activate preview mode."
+            pairedSessionId ? "Open activationUrl on the target origin: it activates the web preview AND forwards its events to the observe session. Use sessionGrant as the X-Walkeros-Preview header for direct server-hop test events." : "Open activationUrl on the target origin to activate preview mode."
           ]
         });
       }
@@ -1333,30 +1347,336 @@ function registerObserveJourneysTool(server, client) {
   );
 }
 
-// src/tools/feedback.ts
+// src/tools/observe-session.ts
 import { z as z7 } from "zod";
 import { mcpResult as mcpResult7, mcpError as mcpError7 } from "@walkeros/core";
-var TITLE7 = "Send Feedback";
-var DESCRIPTION7 = "Send feedback about walkerOS";
+var TITLE7 = "Observe Session";
+var DESCRIPTION7 = "Open, inspect, or end an Observe session: a time-boxed window on one flow that runtimes attach to as arms. A preview arm streams from a browser, a container arm runs server-side, and both feed ONE shared journeys feed. start opens the window (arms picks which runtimes attach), status reports per-arm state plus recordsReceived and expiresAt, stop ends the whole session including every arm. A flow has at most one session, so status/stop resolve it from flowId when sessionId is omitted. Read the events with observe_journeys; this tool never returns event data and never judges whether events are correct.";
+var HINT_SIMULATE_FIRST = "Simulate before preview: flow_simulate checks mapping with no browser.";
+var HINT_PREVIEW_STREAMS = "Preview streams into this session: mint a link with flow_manage preview_regrant, then open it on your site.";
+var HINT_READ = "Read with observe_journeys (flowId); it is the only read.";
+var HINT_STOP = "End both arms with observe_session stop.";
+var HINT_EMPTY_FEED = "recordsReceived is 0: nothing has reached the feed yet. Drive traffic on an attached arm.";
+var HINT_ENDED = "Session ended and both arms detached. Start a new one with observe_session start.";
+var HINT_NO_WINDOW = "No Observe session on this flow. Open one with observe_session start.";
 var inputSchema7 = {
-  text: z7.string().describe("Your feedback text"),
-  anonymous: z7.boolean().optional().describe(
-    "Include user/project info? false = include, true = anonymous. Only needed on first call if not yet configured."
+  action: z7.enum(["start", "status", "stop"]).describe(
+    "start opens a session, status reports arm state, stop ends the whole session."
+  ),
+  flowId: z7.string().describe("Flow the Observe session runs on."),
+  projectId: z7.string().optional().describe("Project ID. Optional; falls back to the default project."),
+  sessionId: z7.string().optional().describe(
+    "Session to act on for status/stop. Optional; the flow has at most one session and it is resolved for you."
+  ),
+  arms: z7.object({
+    container: z7.literal(true).optional().describe(
+      "Pass true to attach the server container arm, which selects the flow's server settings when no preview arm is named. Only true is accepted: a web settings that references a server flow always brings its container arm along, so a container cannot be suppressed here."
+    ),
+    preview: z7.string().optional().describe(
+      "Name the flow settings this session observes. A web settings attaches the browser preview arm (plus the container arm of any server flow it references); a server settings attaches the container arm alone. Omit to use the flow's single web settings."
+    )
+  }).optional().describe(
+    "Which runtimes attach. Omit to attach the default preview arm; a web settings that references a server flow brings its container arm with it."
+  ),
+  origins: z7.array(z7.string()).optional().describe(
+    "Bare https origins (https://host[:port]) the session may ingest web events from."
+  ),
+  level: z7.enum(["off", "standard", "trace"]).optional().describe("Container observation verbosity. Defaults to the app's own."),
+  replace: z7.boolean().optional().describe(
+    "Replace the flow's existing window instead of attaching to it. Re-provisions from the new config."
   )
 };
 var annotations7 = {
   readOnlyHint: false,
-  destructiveHint: false,
+  destructiveHint: true,
   idempotentHint: false,
   openWorldHint: true
 };
-function createFeedbackToolSpec(client) {
+function readSettings(flow) {
+  if (!flow || typeof flow !== "object") return [];
+  const settings = flow.settings;
+  if (!Array.isArray(settings)) return [];
+  const entries = [];
+  for (const entry of settings) {
+    if (!entry || typeof entry !== "object") continue;
+    const { name, platform } = entry;
+    if (typeof name !== "string") continue;
+    if (platform !== "web" && platform !== "server") continue;
+    entries.push({ name, platform });
+  }
+  return entries;
+}
+function resolveSettingsName(settings, arms) {
+  if (arms?.preview !== void 0) {
+    const named = settings.find((entry) => entry.name === arms.preview);
+    if (!named) {
+      throw new Error(
+        `This flow has no settings named "${arms.preview}". Available: ${describeSettings(settings)}`
+      );
+    }
+    return named.name;
+  }
+  if (arms?.container === true) {
+    const servers = settings.filter((entry) => entry.platform === "server");
+    const only = servers[0];
+    if (!only) {
+      throw new Error(
+        `The container arm needs a server settings, and this flow has no server settings. Available: ${describeSettings(settings)}`
+      );
+    }
+    if (servers.length > 1) {
+      throw new Error(
+        `This flow has several server settings. Name one with arms.preview. Available: ${describeSettings(settings)}`
+      );
+    }
+    return only.name;
+  }
+  const webs = settings.filter((entry) => entry.platform === "web");
+  const onlyWeb = webs[0];
+  if (onlyWeb && webs.length === 1) return onlyWeb.name;
+  if (webs.length > 1) {
+    throw new Error(
+      `This flow has several web settings. Name one with arms.preview. Available: ${describeSettings(settings)}`
+    );
+  }
+  const onlySettings = settings[0];
+  if (onlySettings && settings.length === 1) return onlySettings.name;
+  throw new Error(
+    `Could not pick a settings to observe. Name one with arms.preview. Available: ${describeSettings(settings)}`
+  );
+}
+function describeSettings(settings) {
+  if (settings.length === 0) return "none";
+  return settings.map((entry) => `${entry.name} (${entry.platform})`).join(", ");
+}
+function toArms(session) {
   return {
-    name: "feedback",
+    preview: {
+      attached: session.web !== null,
+      settingsName: session.observedFlowName,
+      activationUrl: session.web?.activationUrl ?? null,
+      previewEnabled: session.web?.previewEnabled ?? false
+    },
+    container: {
+      attached: session.server !== null,
+      settingsName: session.serverFlowName,
+      endpoint: session.server?.endpoint ?? null
+    }
+  };
+}
+function toSummary(session) {
+  return {
+    sessionId: session.id,
+    flowId: session.flowId,
+    status: session.status,
+    errorMessage: session.errorMessage,
+    expiresAt: session.expiresAt,
+    recordsReceived: session.recordsReceived,
+    arms: toArms(session)
+  };
+}
+var SESSION_RESOLUTION_FAILED = "Could not resolve this flow's Observe session because the journeys read that identifies it is unavailable. Pass sessionId explicitly to act on the session without that lookup.";
+var SessionResolutionError = class extends Error {
+  code;
+  details;
+  constructor(message, cause) {
+    super(message, { cause });
+    this.name = "SessionResolutionError";
+    this.code = readStringField(cause, "code");
+    this.details = readArrayField(cause, "details");
+  }
+};
+function readStringField(source, key) {
+  if (source === null || typeof source !== "object" || !(key in source))
+    return void 0;
+  const value = Reflect.get(source, key);
+  return typeof value === "string" ? value : void 0;
+}
+function readArrayField(source, key) {
+  if (source === null || typeof source !== "object" || !(key in source))
+    return void 0;
+  const value = Reflect.get(source, key);
+  return Array.isArray(value) ? value : void 0;
+}
+async function resolveSessionId(client, options) {
+  try {
+    const result = await client.listJourneys({
+      flowId: options.flowId,
+      ...options.projectId !== void 0 && { projectId: options.projectId },
+      limit: 1
+    });
+    return result.sessionId;
+  } catch (error) {
+    if (isAuthError(error)) throw error;
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new SessionResolutionError(
+      `${SESSION_RESOLUTION_FAILED} (${detail})`,
+      error
+    );
+  }
+}
+function resolveProjectId(client, projectId) {
+  return projectId ?? client.getDefaultProject();
+}
+var NO_DEFAULT_PROJECT_ERROR2 = "No project ID given and no default project set. Pass projectId or set one with project_manage set_default.";
+function createObserveSessionToolSpec(client) {
+  return {
+    name: "observe_session",
     title: TITLE7,
     description: DESCRIPTION7,
     inputSchema: inputSchema7,
     annotations: annotations7,
+    handler: (input) => observeSessionHandlerBody(client, input)
+  };
+}
+async function observeSessionHandlerBody(client, input) {
+  const {
+    action,
+    flowId,
+    projectId,
+    sessionId,
+    arms,
+    origins,
+    level,
+    replace
+  } = input ?? {};
+  if (!flowId) {
+    return mcpError7(new Error("flowId is required for observe_session."));
+  }
+  const resolvedProjectId = resolveProjectId(client, projectId);
+  if (!resolvedProjectId) {
+    return mcpError7(new Error(NO_DEFAULT_PROJECT_ERROR2));
+  }
+  try {
+    switch (action) {
+      case "start": {
+        if (!client.startObserveSession) {
+          return mcpError7(
+            new Error("observe_session start is not supported by this client.")
+          );
+        }
+        const settings = readSettings(
+          await client.getFlow({
+            flowId,
+            projectId: resolvedProjectId,
+            fields: ["settings"]
+          })
+        );
+        const settingsName = resolveSettingsName(settings, arms);
+        const session = await client.startObserveSession({
+          projectId: resolvedProjectId,
+          flowId,
+          settingsName,
+          ...origins !== void 0 && { origins },
+          ...level !== void 0 && { level },
+          ...replace !== void 0 && { replace }
+        });
+        return mcpResult7(toSummary(session), {
+          next: [HINT_SIMULATE_FIRST, HINT_PREVIEW_STREAMS, HINT_READ]
+        });
+      }
+      case "status": {
+        if (!client.getObserveSession) {
+          return mcpError7(
+            new Error(
+              "observe_session status is not supported by this client."
+            )
+          );
+        }
+        const resolvedSessionId = sessionId ?? await resolveSessionId(client, {
+          flowId,
+          projectId: resolvedProjectId
+        });
+        if (!resolvedSessionId) {
+          return mcpResult7(
+            { sessionId: null, flowId },
+            { next: [HINT_NO_WINDOW, HINT_SIMULATE_FIRST] }
+          );
+        }
+        const session = await client.getObserveSession({
+          projectId: resolvedProjectId,
+          flowId,
+          sessionId: resolvedSessionId
+        });
+        return mcpResult7(toSummary(session), {
+          next: session.recordsReceived === 0 ? [HINT_EMPTY_FEED, HINT_READ, HINT_STOP] : [HINT_READ, HINT_STOP]
+        });
+      }
+      case "stop": {
+        if (!client.endObserveSession) {
+          return mcpError7(
+            new Error("observe_session stop is not supported by this client.")
+          );
+        }
+        const resolvedSessionId = sessionId ?? await resolveSessionId(client, {
+          flowId,
+          projectId: resolvedProjectId
+        });
+        if (!resolvedSessionId) {
+          return mcpResult7(
+            { sessionId: null, flowId, ended: false },
+            { next: [HINT_NO_WINDOW] }
+          );
+        }
+        await client.endObserveSession({
+          projectId: resolvedProjectId,
+          flowId,
+          sessionId: resolvedSessionId
+        });
+        return mcpResult7(
+          { sessionId: resolvedSessionId, flowId, ended: true },
+          { next: [HINT_ENDED] }
+        );
+      }
+      default:
+        throw new Error(
+          `Unknown action: ${String(action)}. Use one of: start, status, stop`
+        );
+    }
+  } catch (error) {
+    return mcpError7(error, isAuthError(error) ? AUTH_HINT : void 0);
+  }
+}
+function registerObserveSessionTool(server, client) {
+  const spec = createObserveSessionToolSpec(client);
+  server.registerTool(
+    spec.name,
+    {
+      title: spec.title,
+      description: spec.description,
+      inputSchema: spec.inputSchema,
+      annotations: spec.annotations
+    },
+    // SDK infers handler type from inputSchema shape; ToolSpec.handler is the
+    // type-erased (input: unknown) => Promise<unknown> form by design.
+    spec.handler
+  );
+}
+
+// src/tools/feedback.ts
+import { z as z8 } from "zod";
+import { mcpResult as mcpResult8, mcpError as mcpError8 } from "@walkeros/core";
+var TITLE8 = "Send Feedback";
+var DESCRIPTION8 = "Send feedback about walkerOS";
+var inputSchema8 = {
+  text: z8.string().describe("Your feedback text"),
+  anonymous: z8.boolean().optional().describe(
+    "Include user/project info? false = include, true = anonymous. Only needed on first call if not yet configured."
+  )
+};
+var annotations8 = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true
+};
+function createFeedbackToolSpec(client) {
+  return {
+    name: "feedback",
+    title: TITLE8,
+    description: DESCRIPTION8,
+    inputSchema: inputSchema8,
+    annotations: annotations8,
     handler: (input) => feedbackHandlerBody(client, input)
   };
 }
@@ -1365,7 +1685,7 @@ async function feedbackHandlerBody(client, input) {
   try {
     let anonymous = client.getFeedbackPreference();
     if (anonymous === void 0 && explicitAnonymous === void 0) {
-      return mcpResult7(
+      return mcpResult8(
         { needsConsent: true },
         {
           next: [
@@ -1382,11 +1702,11 @@ async function feedbackHandlerBody(client, input) {
     const isAnonymous = explicitAnonymous ?? anonymous ?? true;
     await client.submitFeedback(text, {
       anonymous: isAnonymous,
-      version: "4.3.1"
+      version: "4.3.2"
     });
-    return mcpResult7({ ok: true });
+    return mcpResult8({ ok: true });
   } catch (error) {
-    return mcpError7(error);
+    return mcpError8(error);
   }
 }
 function registerFeedbackTool(server, client) {
@@ -1408,93 +1728,93 @@ function registerFeedbackTool(server, client) {
 // src/tools/validate.ts
 import { validate, loadJsonConfig } from "@walkeros/cli";
 import { schemas } from "@walkeros/cli/dev";
-import { mcpResult as mcpResult8, mcpError as mcpError8 } from "@walkeros/core";
+import { mcpResult as mcpResult9, mcpError as mcpError9 } from "@walkeros/core";
 
 // src/schemas/output.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var ValidateOutputShape = {
-  valid: z8.boolean().describe("Whether validation passed"),
-  type: z8.union([
-    z8.enum(["contract", "entry", "event", "flow", "mapping"]),
-    z8.string().regex(/^(destinations|sources|transformers)\.\w+$/)
+  valid: z9.boolean().describe("Whether validation passed"),
+  type: z9.union([
+    z9.enum(["contract", "entry", "event", "flow", "mapping"]),
+    z9.string().regex(/^(destinations|sources|transformers)\.\w+$/)
   ]).describe("What was validated"),
-  errors: z8.array(
-    z8.object({
-      path: z8.string(),
-      message: z8.string(),
-      value: z8.unknown().optional(),
-      code: z8.string().optional()
+  errors: z9.array(
+    z9.object({
+      path: z9.string(),
+      message: z9.string(),
+      value: z9.unknown().optional(),
+      code: z9.string().optional()
     })
   ).describe("Validation errors"),
-  warnings: z8.array(
-    z8.object({
-      path: z8.string(),
-      message: z8.string(),
-      suggestion: z8.string().optional()
+  warnings: z9.array(
+    z9.object({
+      path: z9.string(),
+      message: z9.string(),
+      suggestion: z9.string().optional()
     })
   ).describe("Validation warnings"),
-  details: z8.record(z8.string(), z8.unknown()).describe("Additional validation details")
+  details: z9.record(z9.string(), z9.unknown()).describe("Additional validation details")
 };
 var BundleOutputShape = {
-  success: z8.boolean().describe("Whether bundling succeeded"),
-  totalSize: z8.number().optional().describe("Total bundle size in bytes"),
-  buildTime: z8.number().optional().describe("Build time in milliseconds"),
-  packages: z8.array(
-    z8.object({
-      name: z8.string()
+  success: z9.boolean().describe("Whether bundling succeeded"),
+  totalSize: z9.number().optional().describe("Total bundle size in bytes"),
+  buildTime: z9.number().optional().describe("Build time in milliseconds"),
+  packages: z9.array(
+    z9.object({
+      name: z9.string()
     })
   ).optional().describe("Names of packages included in the bundle"),
-  treeshakingEffective: z8.boolean().optional().describe("Whether tree-shaking was effective"),
-  message: z8.string().optional().describe("Status message")
+  treeshakingEffective: z9.boolean().optional().describe("Whether tree-shaking was effective"),
+  message: z9.string().optional().describe("Status message")
 };
 var SimulateOutputShape = {
-  success: z8.boolean().describe("Whether simulation succeeded"),
-  error: z8.string().optional().describe("Error message if failed"),
-  summary: z8.string().describe("One-line result summary"),
-  destinations: z8.record(
-    z8.string(),
-    z8.object({
-      received: z8.boolean().describe("Whether destination received the event"),
-      calls: z8.number().describe("Number of API calls made"),
-      payload: z8.unknown().optional().describe("All intercepted API calls (only when verbose: true)")
+  success: z9.boolean().describe("Whether simulation succeeded"),
+  error: z9.string().optional().describe("Error message if failed"),
+  summary: z9.string().describe("One-line result summary"),
+  destinations: z9.record(
+    z9.string(),
+    z9.object({
+      received: z9.boolean().describe("Whether destination received the event"),
+      calls: z9.number().describe("Number of API calls made"),
+      payload: z9.unknown().optional().describe("All intercepted API calls (only when verbose: true)")
     })
   ).optional().describe("Per-destination results"),
-  capturedEvents: z8.array(z8.record(z8.string(), z8.unknown())).optional().describe("Events captured by source simulation"),
-  duration: z8.number().optional().describe("Simulation duration in ms")
+  capturedEvents: z9.array(z9.record(z9.string(), z9.unknown())).optional().describe("Events captured by source simulation"),
+  duration: z9.number().optional().describe("Simulation duration in ms")
 };
 var PushOutputShape = {
-  success: z8.boolean().describe("Whether push succeeded"),
-  elbResult: z8.unknown().optional().describe("Push result from the collector"),
-  duration: z8.number().describe("Push duration in milliseconds"),
-  error: z8.string().optional().describe("Error message if push failed")
+  success: z9.boolean().describe("Whether push succeeded"),
+  elbResult: z9.unknown().optional().describe("Push result from the collector"),
+  duration: z9.number().describe("Push duration in milliseconds"),
+  error: z9.string().optional().describe("Error message if push failed")
 };
 var ExamplesListOutputShape = {
-  flow: z8.string().describe("Flow name"),
-  count: z8.number().describe("Number of examples found"),
-  examples: z8.array(
-    z8.object({
-      step: z8.string().describe('Step location (e.g., "destination.gtag")'),
-      stepType: z8.enum(["source", "transformer", "destination"]).describe("Step type"),
-      stepName: z8.string().describe("Step name"),
-      exampleName: z8.string().describe("Example name"),
-      source: z8.enum(["inline", "package"]).describe(
+  flow: z9.string().describe("Flow name"),
+  count: z9.number().describe("Number of examples found"),
+  examples: z9.array(
+    z9.object({
+      step: z9.string().describe('Step location (e.g., "destination.gtag")'),
+      stepType: z9.enum(["source", "transformer", "destination"]).describe("Step type"),
+      stepName: z9.string().describe("Step name"),
+      exampleName: z9.string().describe("Example name"),
+      source: z9.enum(["inline", "package"]).describe(
         'Where the example came from: "inline" (defined in the flow step) or "package" (shipped by the referenced package)'
       ),
-      title: z8.string().optional().describe("Human-readable title if set"),
-      description: z8.string().optional().describe("Short human-readable description"),
-      public: z8.boolean().optional().describe(
+      title: z9.string().optional().describe("Human-readable title if set"),
+      description: z9.string().optional().describe("Short human-readable description"),
+      public: z9.boolean().optional().describe(
         "Whether the example is public (defaults to true if omitted)"
       ),
-      hasIn: z8.boolean().describe("Whether the example has an input value"),
-      hasOut: z8.boolean().describe("Whether the example has an output value"),
-      hasMapping: z8.boolean().describe("Whether the example has a mapping configuration"),
-      hasTrigger: z8.boolean().describe("Whether the example has trigger metadata"),
-      in: z8.unknown().optional().describe("Input event data"),
-      out: z8.unknown().optional().describe("Expected output data"),
-      mapping: z8.unknown().optional().describe("Mapping configuration for destinations"),
-      trigger: z8.object({
-        type: z8.string().optional(),
-        options: z8.unknown().optional()
+      hasIn: z9.boolean().describe("Whether the example has an input value"),
+      hasOut: z9.boolean().describe("Whether the example has an output value"),
+      hasMapping: z9.boolean().describe("Whether the example has a mapping configuration"),
+      hasTrigger: z9.boolean().describe("Whether the example has trigger metadata"),
+      in: z9.unknown().optional().describe("Input event data"),
+      out: z9.unknown().optional().describe("Expected output data"),
+      mapping: z9.unknown().optional().describe("Mapping configuration for destinations"),
+      trigger: z9.object({
+        type: z9.string().optional(),
+        options: z9.unknown().optional()
       }).optional().describe("Trigger metadata for source simulation")
     })
   ).describe("Step examples")
@@ -1529,10 +1849,10 @@ function detectDeprecatedStorePackages(config) {
   }
   return errors;
 }
-var TITLE8 = "Validate Flow";
-var DESCRIPTION8 = "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 inputSchema8 = schemas.ValidateInputShape;
-var annotations8 = {
+var TITLE9 = "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 inputSchema9 = schemas.ValidateInputShape;
+var annotations9 = {
   readOnlyHint: true,
   destructiveHint: false,
   idempotentHint: true,
@@ -1541,10 +1861,10 @@ var annotations8 = {
 function createFlowValidateToolSpec() {
   return {
     name: "flow_validate",
-    title: TITLE8,
-    description: DESCRIPTION8,
-    inputSchema: inputSchema8,
-    annotations: annotations8,
+    title: TITLE9,
+    description: DESCRIPTION9,
+    inputSchema: inputSchema9,
+    annotations: annotations9,
     handler: (input) => flowValidateHandlerBody(input)
   };
 }
@@ -1586,9 +1906,9 @@ async function flowValidateHandlerBody(input) {
         "Read walkeros://reference/flow-schema for correct structure"
       ]
     };
-    return mcpResult8(augmented, hints);
+    return mcpResult9(augmented, hints);
   } catch (error) {
-    return mcpError8(
+    return mcpError9(
       error,
       "Check the input parameter \u2014 expected a JSON string, file path, or URL"
     );
@@ -1615,7 +1935,7 @@ function registerFlowValidateTool(server) {
 // src/tools/bundle.ts
 import { bundle } from "@walkeros/cli";
 import { schemas as schemas2 } from "@walkeros/cli/dev";
-import { mcpResult as mcpResult9, mcpError as mcpError9 } from "@walkeros/core";
+import { mcpResult as mcpResult10, mcpError as mcpError10 } from "@walkeros/core";
 
 // src/tools/resolve-config-path.ts
 var API_ID_PREFIX = /^(flow|cfg)_/;
@@ -1627,12 +1947,12 @@ async function resolveConfigPath(client, configPath) {
 }
 
 // src/tools/bundle.ts
-var TITLE9 = "Bundle Flow";
-var DESCRIPTION9 = "Bundle a walkerOS flow configuration into deployable JavaScript. Resolves all destinations, sources, and transformers, then outputs a tree-shaken production bundle. Returns bundle statistics.";
-var inputSchema9 = {
+var TITLE10 = "Bundle Flow";
+var DESCRIPTION10 = "Bundle a walkerOS flow configuration into deployable JavaScript. Resolves all destinations, sources, and transformers, then outputs a tree-shaken production bundle. Returns bundle statistics.";
+var inputSchema10 = {
   ...schemas2.BundleInputShape
 };
-var annotations9 = {
+var annotations10 = {
   readOnlyHint: false,
   destructiveHint: false,
   idempotentHint: false,
@@ -1641,10 +1961,10 @@ var annotations9 = {
 function createFlowBundleToolSpec(client) {
   return {
     name: "flow_bundle",
-    title: TITLE9,
-    description: DESCRIPTION9,
-    inputSchema: inputSchema9,
-    annotations: annotations9,
+    title: TITLE10,
+    description: DESCRIPTION10,
+    inputSchema: inputSchema10,
+    annotations: annotations10,
     handler: (input) => flowBundleHandlerBody(client, input)
   };
 }
@@ -1658,7 +1978,7 @@ async function flowBundleHandlerBody(client, input) {
       buildOverrides: output ? { output } : void 0
     });
     if (!result) {
-      return mcpResult9(
+      return mcpResult10(
         { success: false, message: "Bundle produced no output" },
         {
           warnings: [
@@ -1669,7 +1989,7 @@ async function flowBundleHandlerBody(client, input) {
       );
     }
     const output_ = result;
-    return mcpResult9(
+    return mcpResult10(
       { success: true, ...output_ },
       {
         next: [
@@ -1679,7 +1999,7 @@ async function flowBundleHandlerBody(client, input) {
       }
     );
   } catch (error) {
-    return mcpError9(error, "Run flow_validate for detailed error messages");
+    return mcpError10(error, "Run flow_validate for detailed error messages");
   }
 }
 function registerFlowBundleTool(server, client) {
@@ -1701,7 +2021,7 @@ function registerFlowBundleTool(server, client) {
 }
 
 // src/tools/simulate.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 import {
   simulateSource,
   simulateTransformer,
@@ -1709,7 +2029,7 @@ import {
   simulateCollector
 } from "@walkeros/cli";
 import { schemas as schemas3 } from "@walkeros/cli/dev";
-import { mcpResult as mcpResult10, mcpError as mcpError10 } from "@walkeros/core";
+import { mcpResult as mcpResult11, mcpError as mcpError11 } from "@walkeros/core";
 
 // src/tools/bundle-cache.ts
 import { createHash } from "crypto";
@@ -1797,34 +2117,34 @@ async function getOrBuildBundle(resolvedConfig) {
 }
 
 // src/tools/simulate.ts
-var TITLE10 = "Simulate Flow";
-var DESCRIPTION10 = '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 inputSchema10 = {
+var TITLE11 = "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 = {
   configPath: schemas3.SimulateInputShape.configPath,
-  event: z9.union([z9.record(z9.string(), z9.unknown()), z9.string()]).optional().describe(
+  event: z10.union([z10.record(z10.string(), z10.unknown()), z10.string()]).optional().describe(
     "For destinations: { name, data, consent? }. Include consent (e.g. { marketing: true }) to satisfy destination consent requirements. For sources: { content, trigger? } where content is the walkerOS event { name, data }. Can also be a JSON string or file path."
   ),
   flow: schemas3.SimulateInputShape.flow,
   platform: schemas3.SimulateInputShape.platform,
   // 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: z9.string().describe(
+  step: z10.string().describe(
     'Required. Target step as "type.name" \u2014 e.g. "source.demo", "destination.gtag", "transformer.router".'
   ),
-  verbose: z9.boolean().optional().describe("Include full payload per destination (default: false)"),
-  ingest: z9.record(z9.string(), z9.unknown()).optional().describe(
+  verbose: z10.boolean().optional().describe("Include full payload per destination (default: false)"),
+  ingest: z10.record(z10.string(), z10.unknown()).optional().describe(
     "Pipeline context a transformer reads via ctx.ingest, e.g. { url } for a request decoder. Only used for transformer steps."
   ),
-  state: z9.object({
-    consent: z9.record(z9.string(), z9.unknown()).optional(),
-    user: z9.record(z9.string(), z9.unknown()).optional(),
-    globals: z9.record(z9.string(), z9.unknown()).optional(),
-    timing: z9.number().optional()
+  state: z10.object({
+    consent: z10.record(z10.string(), z10.unknown()).optional(),
+    user: z10.record(z10.string(), z10.unknown()).optional(),
+    globals: z10.record(z10.string(), z10.unknown()).optional(),
+    timing: z10.number().optional()
   }).optional().describe(
     "Collector-state snapshot for collector steps: consent/user/globals/timing. Seeds the collector before enrichment runs."
   )
 };
-var annotations10 = {
+var annotations11 = {
   readOnlyHint: true,
   destructiveHint: false,
   idempotentHint: true,
@@ -1833,10 +2153,10 @@ var annotations10 = {
 function createFlowSimulateToolSpec(client) {
   return {
     name: "flow_simulate",
-    title: TITLE10,
-    description: DESCRIPTION10,
-    inputSchema: inputSchema10,
-    annotations: annotations10,
+    title: TITLE11,
+    description: DESCRIPTION11,
+    inputSchema: inputSchema11,
+    annotations: annotations11,
     handler: (input) => flowSimulateHandlerBody(client, input)
   };
 }
@@ -1936,7 +2256,7 @@ async function flowSimulateHandlerBody(client, input) {
     if (result.step === "source") {
       const eventCount = result.events.length;
       const summary = `Source captured ${eventCount} event${eventCount !== 1 ? "s" : ""}`;
-      return mcpResult10(
+      return mcpResult11(
         {
           success,
           error: errorMessage,
@@ -1954,7 +2274,7 @@ async function flowSimulateHandlerBody(client, input) {
       );
     }
     if (result.step === "transformer") {
-      return mcpResult10(
+      return mcpResult11(
         {
           success,
           error: errorMessage,
@@ -1968,7 +2288,7 @@ async function flowSimulateHandlerBody(client, input) {
       );
     }
     if (result.step === "collector") {
-      return mcpResult10(
+      return mcpResult11(
         {
           success,
           error: errorMessage,
@@ -2008,7 +2328,7 @@ async function flowSimulateHandlerBody(client, input) {
       destinations,
       duration: result.duration
     };
-    return mcpResult10(resultObj, {
+    return mcpResult11(resultObj, {
       next: ["Use flow_bundle to build for production"],
       ...warnings.length > 0 ? { warnings } : {}
     });
@@ -2018,7 +2338,7 @@ 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 mcpError10(error, hint);
+    return mcpError11(error, hint);
   }
 }
 function registerFlowSimulateTool(server, client) {
@@ -2040,21 +2360,21 @@ function registerFlowSimulateTool(server, client) {
 }
 
 // src/tools/push.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 import { push } from "@walkeros/cli";
 import { schemas as schemas4 } from "@walkeros/cli/dev";
-import { mcpResult as mcpResult11, mcpError as mcpError11 } from "@walkeros/core";
-var TITLE11 = "Push Events";
-var DESCRIPTION11 = "Push a real event through a walkerOS flow to actual destinations. Makes real API calls to real endpoints. Best suited for server-side flows \u2014 web flows should use flow_simulate for testing.";
-var inputSchema11 = {
+import { mcpResult as mcpResult12, mcpError as mcpError12 } from "@walkeros/core";
+var TITLE12 = "Push Events";
+var DESCRIPTION12 = "Push a real event through a walkerOS flow to actual destinations. Makes real API calls to real endpoints. Best suited for server-side flows \u2014 web flows should use flow_simulate for testing.";
+var inputSchema12 = {
   configPath: schemas4.PushInputShape.configPath,
-  event: z10.record(z10.string(), z10.unknown()).describe(
+  event: z11.record(z11.string(), z11.unknown()).describe(
     'Event object, e.g. { name: "page view", data: { title: "Home" } }'
   ),
   flow: schemas4.PushInputShape.flow,
   platform: schemas4.PushInputShape.platform
 };
-var annotations11 = {
+var annotations12 = {
   readOnlyHint: false,
   destructiveHint: true,
   idempotentHint: false,
@@ -2063,10 +2383,10 @@ var annotations11 = {
 function createFlowPushToolSpec() {
   return {
     name: "flow_push",
-    title: TITLE11,
-    description: DESCRIPTION11,
-    inputSchema: inputSchema11,
-    annotations: annotations11,
+    title: TITLE12,
+    description: DESCRIPTION12,
+    inputSchema: inputSchema12,
+    annotations: annotations12,
     handler: (input) => flowPushHandlerBody(input)
   };
 }
@@ -2079,14 +2399,14 @@ async function flowPushHandlerBody(input) {
       platform
     });
     if (!result.success) {
-      return mcpError11(
+      return mcpError12(
         new Error(result.error || "Push failed"),
         "Check destination configuration and connectivity."
       );
     }
-    return mcpResult11(result);
+    return mcpResult12(result);
   } catch (error) {
-    return mcpError11(
+    return mcpError12(
       error,
       "Check configPath and event format. For web flows, use flow_simulate."
     );
@@ -2111,16 +2431,16 @@ function registerFlowPushTool(server) {
 }
 
 // src/tools/examples.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 import { loadJsonConfig as loadJsonConfig2 } from "@walkeros/cli";
-import { fetchPackage, mcpResult as mcpResult12, mcpError as mcpError12 } from "@walkeros/core";
+import { fetchPackage, mcpResult as mcpResult13, mcpError as mcpError13 } from "@walkeros/core";
 
 // src/catalog.ts
 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.3.1";
+var CLIENT_HEADER = "walkeros-mcp/4.3.2";
 function getPackageBaseUrl() {
   return process.env.WALKEROS_APP_URL || void 0;
 }
@@ -2273,20 +2593,20 @@ function applyFilters(entries, filters) {
 }
 
 // src/tools/examples.ts
-var TITLE12 = "Flow Examples";
-var DESCRIPTION12 = '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 inputSchema12 = {
-  configPath: z11.string().min(1).describe("Path to flow configuration file, URL, or inline JSON string"),
-  flow: z11.string().optional().describe("Flow name for multi-flow configs"),
-  step: z11.string().optional().describe('Filter to a specific step (e.g., "destination.gtag")'),
-  full: z11.boolean().optional().describe(
+var TITLE13 = "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 inputSchema13 = {
+  configPath: z12.string().min(1).describe("Path to flow configuration file, URL, or inline JSON string"),
+  flow: z12.string().optional().describe("Flow name for multi-flow configs"),
+  step: z12.string().optional().describe('Filter to a specific step (e.g., "destination.gtag")'),
+  full: z12.boolean().optional().describe(
     "Return full in/out/mapping data for each example (default: false, returns metadata only)"
   ),
-  includeHidden: z11.boolean().optional().describe(
+  includeHidden: z12.boolean().optional().describe(
     "Include examples marked public: false (default: false). Set true for test/debug discovery."
   )
 };
-var annotations12 = {
+var annotations13 = {
   readOnlyHint: true,
   destructiveHint: false,
   idempotentHint: true,
@@ -2295,10 +2615,10 @@ var annotations12 = {
 function createFlowExamplesToolSpec() {
   return {
     name: "flow_examples",
-    title: TITLE12,
-    description: DESCRIPTION12,
-    inputSchema: inputSchema12,
-    annotations: annotations12,
+    title: TITLE13,
+    description: DESCRIPTION13,
+    inputSchema: inputSchema13,
+    annotations: annotations13,
     handler: (input) => flowExamplesHandlerBody(input)
   };
 }
@@ -2393,9 +2713,9 @@ async function flowExamplesHandlerBody(input) {
         "No examples found. Add examples to step entries, or reference a package that ships examples (see package_get)."
       ];
     }
-    return mcpResult12(result, hints);
+    return mcpResult13(result, hints);
   } catch (error) {
-    return mcpError12(error, "Check configPath \u2014 expected a flow.json file");
+    return mcpError13(error, "Check configPath \u2014 expected a flow.json file");
   }
 }
 function registerFlowExamplesTool(server) {
@@ -2417,9 +2737,9 @@ function registerFlowExamplesTool(server) {
 }
 
 // src/tools/flow-load.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 import { loadJsonConfig as loadJsonConfig3 } from "@walkeros/cli";
-import { mcpResult as mcpResult13, mcpError as mcpError13 } from "@walkeros/core";
+import { mcpResult as mcpResult14, mcpError as mcpError14 } from "@walkeros/core";
 var API_ID_PREFIX2 = /^(flow|cfg)_/;
 var WEB_SKELETON = {
   version: 4,
@@ -2441,21 +2761,21 @@ var SERVER_SKELETON = {
     }
   }
 };
-var TITLE13 = "Load or Create Flow";
-var DESCRIPTION13 = "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 inputSchema13 = {
-  source: z12.string().optional().describe(
+var TITLE14 = "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 inputSchema14 = {
+  source: z13.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."
   ),
-  platform: z12.enum(["web", "server"]).optional().describe(
+  platform: z13.enum(["web", "server"]).optional().describe(
     "Platform for new flows. Required when source is omitted. web = browser tracking, server = Node.js HTTP."
   )
 };
 var outputSchema = {
-  version: z12.number().describe("Flow config version"),
-  flows: z12.record(z12.string(), z12.unknown()).describe("Flow entries")
+  version: z13.number().describe("Flow config version"),
+  flows: z13.record(z13.string(), z13.unknown()).describe("Flow entries")
 };
-var annotations13 = {
+var annotations14 = {
   readOnlyHint: true,
   destructiveHint: false,
   idempotentHint: true,
@@ -2464,10 +2784,10 @@ var annotations13 = {
 function createFlowLoadToolSpec(client) {
   return {
     name: "flow_load",
-    title: TITLE13,
-    description: DESCRIPTION13,
-    inputSchema: inputSchema13,
-    annotations: annotations13,
+    title: TITLE14,
+    description: DESCRIPTION14,
+    inputSchema: inputSchema14,
+    annotations: annotations14,
     handler: (input) => flowLoadHandlerBody(client, input)
   };
 }
@@ -2476,7 +2796,7 @@ async function flowLoadHandlerBody(client, input) {
   if (source && API_ID_PREFIX2.test(source)) {
     const resolvedProjectId = resolveDefaultProject(client, void 0);
     if (!resolvedProjectId) {
-      return mcpError13(new Error(NO_DEFAULT_PROJECT_ERROR));
+      return mcpError14(new Error(NO_DEFAULT_PROJECT_ERROR));
     }
     try {
       const flow = await client.getFlow({
@@ -2484,32 +2804,32 @@ async function flowLoadHandlerBody(client, input) {
         projectId: resolvedProjectId
       });
       const config = flow.config;
-      return mcpResult13(
+      return mcpResult14(
         redactNestedStrings(config ?? {}, { skip: keepStructural }),
         {
           next: ["Use flow_validate to check", "Use add-step prompt to modify"]
         }
       );
     } catch (error) {
-      return mcpError13(error, isAuthError(error) ? AUTH_HINT : void 0);
+      return mcpError14(error, isAuthError(error) ? AUTH_HINT : void 0);
     }
   }
   try {
     if (source) {
       const config = await loadJsonConfig3(source);
-      return mcpResult13(redactNestedStrings(config, { skip: keepStructural }), {
+      return mcpResult14(redactNestedStrings(config, { skip: keepStructural }), {
         next: ["Use flow_validate to check", "Use add-step prompt to modify"]
       });
     }
     if (!platform) {
-      return mcpError13(
+      return mcpError14(
         new Error(
           "Provide source (file path, URL, or flow ID) to load existing flow, or platform (web/server) to create a new one."
         )
       );
     }
     const skeleton = platform === "web" ? WEB_SKELETON : SERVER_SKELETON;
-    return mcpResult13(skeleton, {
+    return mcpResult14(skeleton, {
       next: [
         "Read walkeros://reference/flow-schema for config structure",
         "Use add-step prompt to add sources and destinations"
@@ -2518,8 +2838,8 @@ async function flowLoadHandlerBody(client, input) {
   } catch (error) {
     const msg = error instanceof Error ? error.message : "";
     if (msg.includes("not found") || msg.includes("ENOENT"))
-      return mcpError13(error, "Check configPath \u2014 expected a flow.json file");
-    return mcpError13(error);
+      return mcpError14(error, "Check configPath \u2014 expected a flow.json file");
+    return mcpError14(error);
   }
 }
 function registerFlowLoadTool(server, client) {
@@ -2541,18 +2861,18 @@ function registerFlowLoadTool(server, client) {
 }
 
 // src/tools/package.ts
-import { z as z13 } from "zod";
-import { fetchPackage as fetchPackage2, mcpResult as mcpResult14, mcpError as mcpError14 } from "@walkeros/core";
+import { z as z14 } from "zod";
+import { fetchPackage as fetchPackage2, mcpResult as mcpResult15, mcpError as mcpError15 } from "@walkeros/core";
 import { mergeConfigSchema } from "@walkeros/core/dev";
 var SEARCH_TITLE = "Search Package";
 var SEARCH_DESCRIPTION = "Start here for package discovery. Never guess package names: use this tool first to find exact names. Without package name: returns catalog filtered by type/platform. With package name: returns metadata, hint keys, and example summaries.";
 var searchInputSchema = {
-  package: z13.string().min(1).optional().describe(
+  package: z14.string().min(1).optional().describe(
     "Exact npm package name for detailed lookup (e.g., @walkeros/web-destination-snowplow)"
   ),
-  type: z13.enum(["source", "destination", "transformer", "store"]).optional().describe("Filter by package type (browse mode)"),
-  platform: z13.enum(["web", "server"]).optional().describe("Filter by platform (browse mode, includes universal packages)"),
-  version: z13.string().optional().describe("Package version for detailed lookup (default: latest)")
+  type: z14.enum(["source", "destination", "transformer", "store"]).optional().describe("Filter by package type (browse mode)"),
+  platform: z14.enum(["web", "server"]).optional().describe("Filter by platform (browse mode, includes universal packages)"),
+  version: z14.string().optional().describe("Package version for detailed lookup (default: latest)")
 };
 var searchAnnotations = {
   readOnlyHint: true,
@@ -2585,7 +2905,7 @@ async function packageSearchHandlerBody(input) {
       baseUrl
     });
     const result = { catalog: entries, count: entries.length };
-    return mcpResult14(result, {
+    return mcpResult15(result, {
       next: ["Use package_get for schemas and examples"],
       ...warnings.length > 0 ? { warnings } : {}
     });
@@ -2605,11 +2925,11 @@ async function packageSearchHandlerBody(input) {
       hintKeys: info.hintKeys,
       exampleSummaries: info.exampleSummaries
     };
-    return mcpResult14(result, {
+    return mcpResult15(result, {
       next: ["Use package_get for schemas and examples"]
     });
   } catch (error) {
-    return mcpError14(
+    return mcpError15(
       error,
       "Package not found. Use package_search without parameters to browse available packages."
     );
@@ -2634,11 +2954,11 @@ function registerPackageSearchTool(server) {
 var GET_TITLE = "Get Package";
 var GET_DESCRIPTION = 'Requires exact package name: do not guess names, use package_search first to find them. Returns schemas + hint texts + example summaries by default (lightweight). Use section parameter for full content: "hints" (with code blocks), "examples" (full in/out data), or "all".';
 var getInputSchema = {
-  package: z13.string().min(1).describe(
+  package: z14.string().min(1).describe(
     "Exact npm package name (e.g., @walkeros/web-destination-snowplow)"
   ),
-  version: z13.string().optional().describe("Package version (default: latest)"),
-  section: z13.enum(["hints", "examples", "all"]).optional().describe(
+  version: z14.string().optional().describe("Package version (default: latest)"),
+  section: z14.enum(["hints", "examples", "all"]).optional().describe(
     "Section to expand with full content. Default: summary view with schemas + hint texts + example descriptions"
   )
 };
@@ -2707,9 +3027,9 @@ async function packageGetHandlerBody(input) {
     } else {
       result.exampleSummaries = info.exampleSummaries;
     }
-    return mcpResult14(result);
+    return mcpResult15(result);
   } catch (error) {
-    return mcpError14(
+    return mcpError15(
       error,
       "Use package_search to browse available package names."
     );
@@ -2733,7 +3053,7 @@ function registerGetPackageSchemaTool(server) {
 }
 
 // src/tools/diagnostics.ts
-import { mcpResult as mcpResult15 } from "@walkeros/core";
+import { mcpResult as mcpResult16 } from "@walkeros/core";
 import {
   VERSION as CLI_VERSION,
   resolveAppUrl,
@@ -2745,7 +3065,7 @@ var spec_default = {
   openapi: "3.1.0",
   info: {
     title: "walkerOS Tag Manager API",
-    version: "4.0.0",
+    version: "4.1.0",
     description: "API for managing walkerOS flows, projects, and real-time event observation.",
     contact: {
       name: "elbwalker",
@@ -5064,6 +5384,9 @@ var spec_default = {
           },
           sessionGrant: {
             type: "string"
+          },
+          sessionId: {
+            type: "string"
           }
         },
         required: ["grant", "activationUrl", "sessionExpiresAt"]
@@ -5159,6 +5482,13 @@ var spec_default = {
           bundleUrl: {
             type: "string",
             format: "uri"
+          },
+          url: {
+            type: "string",
+            format: "uri"
+          },
+          binding: {
+            type: "string"
           }
         },
         required: [
@@ -17114,10 +17444,10 @@ var spec_default = {
 
 // src/tools/diagnostics.ts
 var CONTRACT_OPENAPI_VERSION = spec_default.info.version;
-var TITLE14 = "Diagnostics";
-var DESCRIPTION14 = "Report the MCP runtime surface: MCP and CLI versions, the resolved app URL and its source, app /api/health reachability, the bundled OpenAPI contract version, and which source served the last package catalog fetch. Read-only and callable when logged out; use it when a request fails to see which versions and backend you are on.";
-var inputSchema14 = {};
-var annotations14 = {
+var TITLE15 = "Diagnostics";
+var DESCRIPTION15 = "Report the MCP runtime surface: MCP and CLI versions, the resolved app URL and its source, app /api/health reachability, the bundled OpenAPI contract version, and which source served the last package catalog fetch. Read-only and callable when logged out; use it when a request fails to see which versions and backend you are on.";
+var inputSchema15 = {};
+var annotations15 = {
   readOnlyHint: true,
   destructiveHint: false,
   idempotentHint: true,
@@ -17126,10 +17456,10 @@ var annotations14 = {
 function createDiagnosticsToolSpec(client, packageVersion) {
   return {
     name: "diagnostics",
-    title: TITLE14,
-    description: DESCRIPTION14,
-    inputSchema: inputSchema14,
-    annotations: annotations14,
+    title: TITLE15,
+    description: DESCRIPTION15,
+    inputSchema: inputSchema15,
+    annotations: annotations15,
     handler: () => diagnosticsHandlerBody(client, packageVersion)
   };
 }
@@ -17188,7 +17518,7 @@ async function diagnosticsHandlerBody(client, packageVersion) {
       partial: catalogInfo.partial
     } : { lastSource: void 0, lastCount: void 0, partial: void 0 }
   };
-  return mcpResult15(result, warnings.length > 0 ? { warnings } : void 0);
+  return mcpResult16(result, warnings.length > 0 ? { warnings } : void 0);
 }
 function registerDiagnosticsTool(server, client, packageVersion) {
   const spec = createDiagnosticsToolSpec(client, packageVersion);
@@ -17479,17 +17809,17 @@ function registerReferenceResources(server) {
 }
 
 // src/prompts/add-step.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 function registerAddStepPrompt(server) {
   server.registerPrompt(
     "add-step",
     {
       description: "Add a source, destination, transformer, or store step to a flow configuration. Guides through package selection, config scaffolding, and wiring.",
       argsSchema: {
-        stepType: z14.string().optional().describe(
+        stepType: z15.string().optional().describe(
           "Type of step to add: source, destination, transformer, or store"
         ),
-        flowPath: z14.string().optional().describe("Path to the flow.json file to modify")
+        flowPath: z15.string().optional().describe("Path to the flow.json file to modify")
       }
     },
     async ({ stepType, flowPath }) => ({
@@ -17534,14 +17864,14 @@ function registerAddStepPrompt(server) {
 }
 
 // src/prompts/setup-mapping.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 function registerSetupMappingPrompt(server) {
   server.registerPrompt(
     "setup-mapping",
     {
       description: "Set up event mapping for any step in a flow. Teaches mapping syntax and uses package examples as templates.",
       argsSchema: {
-        stepName: z15.string().optional().describe('Step name in the flow (e.g., "gtag", "meta", "express")')
+        stepName: z16.string().optional().describe('Step name in the flow (e.g., "gtag", "meta", "express")')
       }
     },
     async ({ stepName }) => ({
@@ -17579,14 +17909,14 @@ function registerSetupMappingPrompt(server) {
 }
 
 // src/prompts/manage-contract.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 function registerManageContractPrompt(server) {
   server.registerPrompt(
     "manage-contract",
     {
       description: "Create or update event contracts for a flow. Can generate contracts from existing mappings or scaffold mappings from contracts.",
       argsSchema: {
-        direction: z16.string().optional().describe(
+        direction: z17.string().optional().describe(
           'Direction: "from-mappings" (extract contract from existing mappings), "from-scratch" (create new contract), or "to-mappings" (scaffold mappings from contract)'
         )
       }
@@ -17648,6 +17978,9 @@ var SERVER_INSTRUCTIONS = `walkerOS is an open-source, privacy-first event data
 10. \`flow_simulate({ configPath: "flow.json", event: "..." })\` \u2014 test
 11. \`flow_manage({ action: "update", flowId: "...", content: {...} })\` \u2014 save to cloud
 12. \`deploy_manage({ action: "deploy", flowId: "..." })\` \u2014 deploy
+13. \`observe_session({ action: "start", flowId: "..." })\` - open an Observe session: a time-boxed window on one flow that runtimes attach to as arms
+14. \`flow_manage({ action: "preview_regrant", flowId: "...", previewId: "...", origins: [...] })\` - mint an activation link; minted while the flow is observed, it pairs with that Observe session automatically, so the previewed page streams into the same feed
+15. \`observe_journeys({ flowId: "..." })\` - read what arrived; it is the only read, and it never judges whether events are correct
 
 ## Architecture: Source \u2192 Collector \u2192 Destination(s)
 
@@ -17775,6 +18108,7 @@ function createWalkerOSMcpServer(opts) {
   registerFlowManageTool(server, opts.client);
   registerDeployTool(server, opts.client);
   registerSecretManageTool(server, opts.client);
+  registerObserveSessionTool(server, opts.client);
   registerObserveJourneysTool(server, opts.client);
   registerFeedbackTool(server, opts.client);
   registerDiagnosticsTool(server, opts.client, packageVersion);
@@ -17841,6 +18175,9 @@ import {
   getDeploymentBySlug,
   deleteDeployment,
   listJourneys,
+  startObserveSession,
+  getObserveSession,
+  endObserveSession,
   requestDeviceCode,
   pollForToken,
   whoami,
@@ -17936,6 +18273,21 @@ var HttpToolClient = class {
   async listJourneys(options) {
     return listJourneys(options);
   }
+  /**
+   * Observe session lifecycle over the CLI's authenticated boundary. The trio
+   * routes through the same `apiFetch` as every other method here, so token
+   * resolution, base URL, and `ApiError` shaping (which `isAuthError` reads)
+   * stay identical to the rest of the client.
+   */
+  async startObserveSession(options) {
+    return startObserveSession(options);
+  }
+  async getObserveSession(options) {
+    return getObserveSession(options);
+  }
+  async endObserveSession(options) {
+    return endObserveSession(options);
+  }
   async requestDeviceCode() {
     return requestDeviceCode();
   }
@@ -18007,7 +18359,7 @@ function createStreamableHttpHandler(server, opts = {}) {
 }
 
 // src/tool-definitions.ts
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 import { schemas as schemas6 } from "@walkeros/cli/dev";
 var TOOL_DEFINITIONS = [
   {
@@ -18015,8 +18367,8 @@ var TOOL_DEFINITIONS = [
     title: "Authentication",
     description: "Manage walkerOS authentication. Check login status, log in via device code flow, or log out. No terminal or browser required, the MCP client handles the authorization URL.",
     inputSchema: {
-      action: z17.enum(["status", "login", "logout"]),
-      deviceCode: z17.string().optional()
+      action: z18.enum(["status", "login", "logout"]),
+      deviceCode: z18.string().optional()
     },
     annotations: {
       readOnlyHint: false,
@@ -18030,7 +18382,7 @@ var TOOL_DEFINITIONS = [
     title: "Project Management",
     description: "Manage walkerOS projects. List, create, update, delete projects, or set a default project for CLI operations.",
     inputSchema: {
-      action: z17.enum([
+      action: z18.enum([
         "list",
         "get",
         "create",
@@ -18038,8 +18390,8 @@ var TOOL_DEFINITIONS = [
         "delete",
         "set_default"
       ]),
-      projectId: z17.string().optional(),
-      name: z17.string().optional()
+      projectId: z18.string().optional(),
+      name: z18.string().optional()
     },
     annotations: {
       readOnlyHint: false,
@@ -18053,7 +18405,7 @@ var TOOL_DEFINITIONS = [
     title: "Flow Management",
     description: "Manage walkerOS flows and their previews. List/get/create/update/delete/duplicate flows, or create/inspect/delete preview bundles for testing flow changes on live sites.",
     inputSchema: {
-      action: z17.enum([
+      action: z18.enum([
         "list",
         "get",
         "create",
@@ -18065,19 +18417,19 @@ var TOOL_DEFINITIONS = [
         "preview_create",
         "preview_delete"
       ]),
-      flowId: z17.string().optional(),
-      projectId: z17.string().optional(),
-      name: z17.string().optional(),
-      content: z17.record(z17.string(), z17.unknown()).optional(),
-      patch: z17.boolean().optional(),
-      fields: z17.array(z17.string()).optional(),
-      sort: z17.enum(["name", "updated_at", "created_at"]).optional(),
-      order: z17.enum(["asc", "desc"]).optional(),
-      includeDeleted: z17.boolean().optional(),
-      previewId: z17.string().optional(),
-      flowName: z17.string().optional(),
-      flowSettingsId: z17.string().optional(),
-      siteUrl: z17.string().optional()
+      flowId: z18.string().optional(),
+      projectId: z18.string().optional(),
+      name: z18.string().optional(),
+      content: z18.record(z18.string(), z18.unknown()).optional(),
+      patch: z18.boolean().optional(),
+      fields: z18.array(z18.string()).optional(),
+      sort: z18.enum(["name", "updated_at", "created_at"]).optional(),
+      order: z18.enum(["asc", "desc"]).optional(),
+      includeDeleted: z18.boolean().optional(),
+      previewId: z18.string().optional(),
+      flowName: z18.string().optional(),
+      flowSettingsId: z18.string().optional(),
+      siteUrl: z18.string().optional()
     },
     annotations: {
       readOnlyHint: false,
@@ -18091,14 +18443,14 @@ var TOOL_DEFINITIONS = [
     title: "Deploy Management",
     description: "Deploy walkerOS flows and manage deployments. For get/delete actions pass flowId (required) plus optional slug to disambiguate when a flow has multiple active deployments. If a flow has >=2 active deployments and no slug is supplied, the tool returns a MULTIPLE_DEPLOYMENTS error with a details[] list showing each deployment's slug, type, status, and updatedAt.",
     inputSchema: {
-      action: z17.enum(["deploy", "list", "get", "delete"]),
-      projectId: z17.string().optional(),
-      flowId: z17.string().optional(),
-      slug: z17.string().optional(),
-      type: z17.enum(["web", "server"]).optional(),
-      status: z17.string().optional(),
-      wait: z17.boolean().optional(),
-      flowName: z17.string().optional()
+      action: z18.enum(["deploy", "list", "get", "delete"]),
+      projectId: z18.string().optional(),
+      flowId: z18.string().optional(),
+      slug: z18.string().optional(),
+      type: z18.enum(["web", "server"]).optional(),
+      status: z18.string().optional(),
+      wait: z18.boolean().optional(),
+      flowName: z18.string().optional()
     },
     annotations: {
       readOnlyHint: false,
@@ -18112,12 +18464,36 @@ var TOOL_DEFINITIONS = [
     title: "Secret Management",
     description: "Manage a flow\u2019s managed secrets (the $secret.<NAME> values its steps reference at deploy/run time). Actions: list (metadata only), set (create), update (rotate value), delete. Secrets are write-mostly: values are encrypted at rest and are NEVER returned, listed, or echoed. Reference a secret from a flow step as $secret.<NAME> (credentials, tokens, and private keys use $secret, not $env).",
     inputSchema: {
-      action: z17.enum(["list", "set", "update", "delete"]),
-      projectId: z17.string().optional(),
-      flowId: z17.string(),
-      name: z17.string().optional(),
-      value: z17.string().optional(),
-      secretId: z17.string().optional()
+      action: z18.enum(["list", "set", "update", "delete"]),
+      projectId: z18.string().optional(),
+      flowId: z18.string(),
+      name: z18.string().optional(),
+      value: z18.string().optional(),
+      secretId: z18.string().optional()
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  {
+    name: "observe_session",
+    title: "Observe Session",
+    description: "Open, inspect, or end an Observe session: a time-boxed window on one flow that runtimes attach to as arms. A preview arm streams from a browser, a container arm runs server-side, and both feed ONE shared journeys feed. start opens the window (arms picks which runtimes attach), status reports per-arm state plus recordsReceived and expiresAt, stop ends the whole session including every arm. A flow has at most one session, so status/stop resolve it from flowId when sessionId is omitted. Read the events with observe_journeys; this tool never returns event data and never judges whether events are correct.",
+    inputSchema: {
+      action: z18.enum(["start", "status", "stop"]),
+      flowId: z18.string(),
+      projectId: z18.string().optional(),
+      sessionId: z18.string().optional(),
+      arms: z18.object({
+        container: z18.literal(true).optional(),
+        preview: z18.string().optional()
+      }).optional(),
+      origins: z18.array(z18.string()).optional(),
+      level: z18.enum(["off", "standard", "trace"]).optional(),
+      replace: z18.boolean().optional()
     },
     annotations: {
       readOnlyHint: false,
@@ -18131,10 +18507,10 @@ var TOOL_DEFINITIONS = [
     title: "Observe Journeys",
     description: "Read the assembled, cross-runtime journeys for a flow that is currently being observed (an active Observe session). Pass flowId; the active session is resolved for you (a flow has at most one). Each journey is one traced event reconstructed end to end across web and server: its ordered hops, per-hop status, captured in/out payloads, consent, and vendor calls. When the flow has no active session the result is { sessionId: null, journeys: [], gaps: [] }. Narrow with traceId (one trace) and limit (1-100, most recent kept; default 50). Read-only.",
     inputSchema: {
-      flowId: z17.string(),
-      projectId: z17.string().optional(),
-      traceId: z17.string().optional(),
-      limit: z17.number().int().min(1).max(100).optional()
+      flowId: z18.string(),
+      projectId: z18.string().optional(),
+      traceId: z18.string().optional(),
+      limit: z18.number().int().min(1).max(100).optional()
     },
     annotations: {
       readOnlyHint: true,
@@ -18161,8 +18537,8 @@ var TOOL_DEFINITIONS = [
     description: "Bundle a walkerOS flow configuration into deployable JavaScript. Resolves all destinations, sources, and transformers, then outputs a tree-shaken production bundle. Returns bundle statistics. Set remote: true to use the walkerOS cloud service instead of local build tools.",
     inputSchema: {
       ...schemas6.BundleInputShape,
-      remote: z17.boolean().optional(),
-      content: z17.record(z17.string(), z17.unknown()).optional()
+      remote: z18.boolean().optional(),
+      content: z18.record(z18.string(), z18.unknown()).optional()
     },
     annotations: {
       readOnlyHint: false,
@@ -18177,11 +18553,11 @@ var TOOL_DEFINITIONS = [
     description: '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? }, env?: {...} }. Use step to target a specific step. Use flow_examples to discover available test data. IMPORTANT: Destinations with require (e.g. require: ["consent"]) stay pending until that collector event fires, 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.',
     inputSchema: {
       configPath: schemas6.SimulateInputShape.configPath,
-      event: z17.union([z17.record(z17.string(), z17.unknown()), z17.string()]).optional(),
+      event: z18.union([z18.record(z18.string(), z18.unknown()), z18.string()]).optional(),
       flow: schemas6.SimulateInputShape.flow,
       platform: schemas6.SimulateInputShape.platform,
       step: schemas6.SimulateInputShape.step,
-      verbose: z17.boolean().optional()
+      verbose: z18.boolean().optional()
     },
     annotations: {
       readOnlyHint: true,
@@ -18196,7 +18572,7 @@ var TOOL_DEFINITIONS = [
     description: "Push a real event through a walkerOS flow to actual destinations. Makes real API calls to real endpoints. Best suited for server-side flows, web flows should use flow_simulate for testing.",
     inputSchema: {
       configPath: schemas6.PushInputShape.configPath,
-      event: z17.record(z17.string(), z17.unknown()),
+      event: z18.record(z18.string(), z18.unknown()),
       flow: schemas6.PushInputShape.flow,
       platform: schemas6.PushInputShape.platform
     },
@@ -18212,11 +18588,11 @@ var TOOL_DEFINITIONS = [
     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.",
     inputSchema: {
-      configPath: z17.string().min(1),
-      flow: z17.string().optional(),
-      step: z17.string().optional(),
-      full: z17.boolean().optional(),
-      includeHidden: z17.boolean().optional()
+      configPath: z18.string().min(1),
+      flow: z18.string().optional(),
+      step: z18.string().optional(),
+      full: z18.boolean().optional(),
+      includeHidden: z18.boolean().optional()
     },
     annotations: {
       readOnlyHint: true,
@@ -18230,8 +18606,8 @@ var TOOL_DEFINITIONS = [
     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.",
     inputSchema: {
-      source: z17.string().optional(),
-      platform: z17.enum(["web", "server"]).optional()
+      source: z18.string().optional(),
+      platform: z18.enum(["web", "server"]).optional()
     },
     annotations: {
       readOnlyHint: true,
@@ -18245,10 +18621,10 @@ var TOOL_DEFINITIONS = [
     title: "Search Package",
     description: "Start here for package discovery. Never guess package names, use this tool first to find exact names. Without package name: returns catalog filtered by type/platform. With package name: returns metadata, hint keys, and example summaries.",
     inputSchema: {
-      package: z17.string().min(1).optional(),
-      type: z17.enum(["source", "destination", "transformer", "store"]).optional(),
-      platform: z17.enum(["web", "server"]).optional(),
-      version: z17.string().optional()
+      package: z18.string().min(1).optional(),
+      type: z18.enum(["source", "destination", "transformer", "store"]).optional(),
+      platform: z18.enum(["web", "server"]).optional(),
+      version: z18.string().optional()
     },
     annotations: {
       readOnlyHint: true,
@@ -18262,9 +18638,9 @@ var TOOL_DEFINITIONS = [
     title: "Get Package",
     description: 'Requires exact package name, do not guess names, use package_search first to find them. Returns schemas + hint texts + example summaries by default (lightweight). Use section parameter for full content: "hints" (with code blocks), "examples" (full in/out data), or "all".',
     inputSchema: {
-      package: z17.string().min(1),
-      version: z17.string().optional(),
-      section: z17.enum(["hints", "examples", "all"]).optional()
+      package: z18.string().min(1),
+      version: z18.string().optional(),
+      section: z18.enum(["hints", "examples", "all"]).optional()
     },
     annotations: {
       readOnlyHint: true,
@@ -18278,8 +18654,8 @@ var TOOL_DEFINITIONS = [
     title: "Send Feedback",
     description: "Send feedback about walkerOS",
     inputSchema: {
-      text: z17.string(),
-      anonymous: z17.boolean().optional()
+      text: z18.string(),
+      anonymous: z18.boolean().optional()
     },
     annotations: {
       readOnlyHint: false,
@@ -18298,6 +18674,7 @@ function createToolHandlers(client, packageVersion = "0.0.0") {
     createFlowManageToolSpec(client),
     createDeployManageToolSpec(client),
     createSecretManageToolSpec(client),
+    createObserveSessionToolSpec(client),
     createObserveJourneysToolSpec(client),
     createFeedbackToolSpec(client),
     createFlowValidateToolSpec(),
@@ -18313,7 +18690,15 @@ function createToolHandlers(client, packageVersion = "0.0.0") {
   return Object.fromEntries(specs.map((s) => [s.name, s]));
 }
 export {
+  HINT_EMPTY_FEED,
+  HINT_ENDED,
+  HINT_NO_WINDOW,
+  HINT_PREVIEW_STREAMS,
+  HINT_READ,
+  HINT_SIMULATE_FIRST,
+  HINT_STOP,
   HttpToolClient,
+  DESCRIPTION7 as OBSERVE_SESSION_DESCRIPTION,
   TOOL_DEFINITIONS,
   createStreamableHttpHandler,
   createToolHandlers,