@walkeros/mcp 4.3.1 → 4.3.2

package/dist/stdio.js

@@ -722,7 +722,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.3.1";
+var CLIENT_HEADER = "walkeros-mcp/4.3.2";
 function getPackageBaseUrl() {
   return process.env.WALKEROS_APP_URL || void 0;
 }
@@ -1466,7 +1466,7 @@ 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 mcpResult8({ ok: true });
   } catch (error) {
@@ -1502,7 +1502,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",
@@ -3821,6 +3821,9 @@ var spec_default = {
           },
           sessionGrant: {
             type: "string"
+          },
+          sessionId: {
+            type: "string"
           }
         },
         required: ["grant", "activationUrl", "sessionExpiresAt"]
@@ -3916,6 +3919,13 @@ var spec_default = {
           bundleUrl: {
             type: "string",
             format: "uri"
+          },
+          url: {
+            type: "string",
+            format: "uri"
+          },
+          binding: {
+            type: "string"
           }
         },
         required: [
@@ -16452,6 +16462,7 @@ var PREVIEW_SUMMARY_FIELDS = [
   "grant",
   "sessionGrant",
   "sessionExpiresAt",
+  "sessionId",
   "status",
   "observeFeed",
   "createdBy",
@@ -16475,6 +16486,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",
@@ -16726,16 +16749,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 mcpResult12(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."
           ]
         });
       }
@@ -17214,6 +17238,312 @@ function registerObserveJourneysTool(server, client) {
   );
 }
 
+// src/tools/observe-session.ts
+import { z as z14 } from "zod";
+import { mcpResult as mcpResult16, mcpError as mcpError15 } from "@walkeros/core";
+var TITLE15 = "Observe Session";
+var DESCRIPTION15 = "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 inputSchema15 = {
+  action: z14.enum(["start", "status", "stop"]).describe(
+    "start opens a session, status reports arm state, stop ends the whole session."
+  ),
+  flowId: z14.string().describe("Flow the Observe session runs on."),
+  projectId: z14.string().optional().describe("Project ID. Optional; falls back to the default project."),
+  sessionId: z14.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: z14.object({
+    container: z14.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: z14.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: z14.array(z14.string()).optional().describe(
+    "Bare https origins (https://host[:port]) the session may ingest web events from."
+  ),
+  level: z14.enum(["off", "standard", "trace"]).optional().describe("Container observation verbosity. Defaults to the app's own."),
+  replace: z14.boolean().optional().describe(
+    "Replace the flow's existing window instead of attaching to it. Re-provisions from the new config."
+  )
+};
+var annotations15 = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: true
+};
+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 {
+    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: TITLE15,
+    description: DESCRIPTION15,
+    inputSchema: inputSchema15,
+    annotations: annotations15,
+    handler: (input) => observeSessionHandlerBody(client, input)
+  };
+}
+async function observeSessionHandlerBody(client, input) {
+  const {
+    action,
+    flowId,
+    projectId,
+    sessionId,
+    arms,
+    origins,
+    level,
+    replace
+  } = input ?? {};
+  if (!flowId) {
+    return mcpError15(new Error("flowId is required for observe_session."));
+  }
+  const resolvedProjectId = resolveProjectId(client, projectId);
+  if (!resolvedProjectId) {
+    return mcpError15(new Error(NO_DEFAULT_PROJECT_ERROR2));
+  }
+  try {
+    switch (action) {
+      case "start": {
+        if (!client.startObserveSession) {
+          return mcpError15(
+            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 mcpResult16(toSummary(session), {
+          next: [HINT_SIMULATE_FIRST, HINT_PREVIEW_STREAMS, HINT_READ]
+        });
+      }
+      case "status": {
+        if (!client.getObserveSession) {
+          return mcpError15(
+            new Error(
+              "observe_session status is not supported by this client."
+            )
+          );
+        }
+        const resolvedSessionId = sessionId ?? await resolveSessionId(client, {
+          flowId,
+          projectId: resolvedProjectId
+        });
+        if (!resolvedSessionId) {
+          return mcpResult16(
+            { sessionId: null, flowId },
+            { next: [HINT_NO_WINDOW, HINT_SIMULATE_FIRST] }
+          );
+        }
+        const session = await client.getObserveSession({
+          projectId: resolvedProjectId,
+          flowId,
+          sessionId: resolvedSessionId
+        });
+        return mcpResult16(toSummary(session), {
+          next: session.recordsReceived === 0 ? [HINT_EMPTY_FEED, HINT_READ, HINT_STOP] : [HINT_READ, HINT_STOP]
+        });
+      }
+      case "stop": {
+        if (!client.endObserveSession) {
+          return mcpError15(
+            new Error("observe_session stop is not supported by this client.")
+          );
+        }
+        const resolvedSessionId = sessionId ?? await resolveSessionId(client, {
+          flowId,
+          projectId: resolvedProjectId
+        });
+        if (!resolvedSessionId) {
+          return mcpResult16(
+            { sessionId: null, flowId, ended: false },
+            { next: [HINT_NO_WINDOW] }
+          );
+        }
+        await client.endObserveSession({
+          projectId: resolvedProjectId,
+          flowId,
+          sessionId: resolvedSessionId
+        });
+        return mcpResult16(
+          { 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 mcpError15(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/resources/package-schemas.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { fetchPackageSchema } from "@walkeros/core";
@@ -17484,17 +17814,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 }) => ({
@@ -17539,14 +17869,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 }) => ({
@@ -17584,14 +17914,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)'
         )
       }
@@ -17653,6 +17983,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)
 
@@ -17783,6 +18116,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);
@@ -17849,6 +18183,9 @@ import {
   getDeploymentBySlug,
   deleteDeployment,
   listJourneys,
+  startObserveSession,
+  getObserveSession,
+  endObserveSession,
   requestDeviceCode,
   pollForToken,
   whoami,
@@ -17944,6 +18281,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();
   }
@@ -17994,7 +18346,7 @@ var HttpToolClient = class {
 };
 
 // src/stdio.ts
-setClientContext({ type: "mcp", version: "4.3.1" });
+setClientContext({ type: "mcp", version: "4.3.2" });
 process.on("uncaughtException", (err) => {
   const emitter = getMcpEmitterSingleton();
   if (emitter) {
@@ -18014,7 +18366,7 @@ process.on("unhandledRejection", (reason) => {
 async function main() {
   const server = createWalkerOSMcpServer({
     client: new HttpToolClient(),
-    version: "4.3.1"
+    version: "4.3.2"
   });
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -18024,7 +18376,7 @@ main().catch(async (error) => {
   try {
     const emitter = await createMcpEmitter({
       clientInfo: void 0,
-      packageVersion: "4.3.1"
+      packageVersion: "4.3.2"
     });
     await emitter.emitError("startup");
   } catch {