@walkeros/mcp 4.7.2 → 4.8.0-next-1791441510508

package/dist/index.d.ts

@@ -326,7 +326,7 @@ interface FrameLeanWire {
     extends: string | null;
     source: FrameSourceWire | null;
     origin: 'drawn' | 'imported' | 'observed';
-    flowId: string | null;
+    flowId: string;
     screenshot: FrameScreenshotWire | null;
     version: number;
     createdAt: string;
@@ -507,13 +507,16 @@ interface ToolClient {
     }): Promise<ListKnowledgeWire>;
     listFrames(options: {
         projectId: string;
+        flowId: string;
     }): Promise<FrameLeanListWire>;
     listPageFrames(options: {
         projectId: string;
+        flowId: string;
         pageKey: string;
     }): Promise<FrameListWire>;
     getFrame(options: {
         projectId: string;
+        flowId: string;
         frameId: string;
     }): Promise<FrameWire>;
     requestDeviceCode(): Promise<DeviceAuthorization>;
@@ -909,13 +912,16 @@ declare class HttpToolClient implements ToolClient {
     }): Promise<ListKnowledgeWire>;
     listFrames(options: {
         projectId: string;
+        flowId: string;
     }): Promise<FrameLeanListWire>;
     listPageFrames(options: {
         projectId: string;
+        flowId: string;
         pageKey: string;
     }): Promise<FrameListWire>;
     getFrame(options: {
         projectId: string;
+        flowId: string;
         frameId: string;
     }): Promise<FrameWire>;
     requestDeviceCode(): Promise<DeviceAuthorization>;
@@ -1132,6 +1138,7 @@ declare const FRAME_MANAGE_INPUT_SCHEMA: {
         list: "list";
     }>;
     projectId: z.ZodOptional<z.ZodString>;
+    flowId: z.ZodOptional<z.ZodString>;
     pageKey: z.ZodOptional<z.ZodString>;
     frameId: z.ZodOptional<z.ZodString>;
 };
@@ -1142,7 +1149,7 @@ declare const FRAME_MANAGE_INPUT_SCHEMA: {
  */
 declare const FRAME_HINT_OPEN_PAGE_OR_GET = "Use action \"page\" with a pageKey (a frame\u2019s source.key) to read a page with marks, or action \"get\" with a frameId.";
 declare const FRAME_HINT_NAMES_ARE_DOCUMENTATION = "Frame names are documentation; the marks inside a frame carry the meaning.";
-declare const FRAME_HINT_NONE_YET = "This project has no frames yet. Frames are drawn in Tag Mode or the app, not through this tool.";
+declare const FRAME_HINT_NONE_YET = "This flow has no frames yet. Frames are drawn in Tag Mode or the app, not through this tool.";
 declare const FRAME_HINT_MARK_SPACE = "Tag geometry is fractional: a rect is 0..1 of its frame, and an at is 0..1 of its parent tag\u2019s box, or of the frame for a root tag; a child frame sits inside its parent through placements[].rect.";
 declare const FRAME_HINT_READ_KNOWLEDGE = "Use hub_manage action \"knowledge\" with frameId (and markId) to read what people wrote here. A markId is a tag id from these marks, and a tag\u2019s threadRef is the id of its thread entry there.";
 declare const FRAME_HINT_NONE_ON_PAGE = "No frames on this page. Check the pageKey against the source.key values from action \"list\".";

package/dist/index.js

@@ -502,13 +502,17 @@ var PROJECT_MANAGE_REQUIREMENTS = {
   create: { required: ["name"] }
 };
 var FRAME_MANAGE_REQUIREMENTS = {
+  list: {
+    required: ["flowId"],
+    hint: 'Use flow_manage action "list" to find the flow the frames belong to.'
+  },
   page: {
-    required: ["pageKey"],
-    hint: 'Use action "list" to see the source keys of the project\u2019s frames.'
+    required: ["flowId", "pageKey"],
+    hint: 'Use flow_manage action "list" to find the flow, and action "list" to see the source keys of its frames.'
   },
   get: {
-    required: ["frameId"],
-    hint: 'Use action "list" or "page" to find a frameId.'
+    required: ["flowId", "frameId"],
+    hint: 'Use flow_manage action "list" to find the flow, and action "list" or "page" to find a frameId.'
   }
 };
 
@@ -794,7 +798,7 @@ function safeDetail(flow) {
   };
 }
 var TITLE3 = "Flow Management";
-var DESCRIPTION3 = "Manage walkerOS flows and their previews. List/get/create/update/delete/duplicate flows, or create/inspect/delete preview bundles and mint activation grants (preview_regrant) for testing flow changes on live sites.";
+var DESCRIPTION3 = "Manage walkerOS flows and their previews. List/get/create/update/delete/duplicate flows (deleting a flow deletes its frames too), or create/inspect/delete preview bundles and mint activation grants (preview_regrant) for testing flow changes on live sites.";
 var inputSchema3 = {
   action: z4.enum([
     "list",
@@ -2680,14 +2684,17 @@ import { mcpResult as mcpResult9, mcpError as mcpError10 } from "@walkeros/core"
 var FRAME_ID_PATTERN2 = /^frm_[A-Za-z0-9_-]{21}$/;
 var MAX_PAGE_KEY_CHARS = 1024;
 var TITLE9 = "Frames";
-var FRAME_MANAGE_DESCRIPTION = 'Read the frames of a measurement plan: named rectangles with marks inside them, drawn in Tag Mode or in the app. Actions: list (every frame of the project, without marks), page (the frames of one page at any depth, with marks), get (one frame with its marks). Read-only: frames are drawn and edited in Tag Mode or the app, never here. A frame name is documentation; the marks inside it carry the meaning. A frame that extends another stores only what it adds, so its tags may carry only the fields they change. Marks are { tags, note }: tags is one flat list of tags, each with an id, a kind such as entity, property or action, a name, and a parentId naming the tag it sits under; note is the frame\u2019s own description and thread. Use hub_manage action "knowledge" with a frameId or markId to read what people wrote on a frame. A markId is a tag id: a tag\u2019s id, parentId and threadRef come back literal when they have the shape the app mints, so they can be passed straight back; every other string value in the marks is wrapped as data, and so is an object key that is not a plain identifier.';
+var FRAME_MANAGE_DESCRIPTION = 'Read the frames of a measurement plan: named rectangles with marks inside them, drawn in Tag Mode or in the app. Frames belong to a flow: every action takes the flowId of the flow they live in; use flow_manage action "list" to find one. Actions: list (every frame of the flow, without marks), page (the flow\u2019s frames on one page at any depth, with marks), get (one frame with its marks). Read-only: frames are drawn and edited in Tag Mode or the app, never here. A frame name is documentation; the marks inside it carry the meaning. A frame that extends another stores only what it adds, so its tags may carry only the fields they change. Marks are { tags, note }: tags is one flat list of tags, each with an id, a kind such as entity, property or action, a name, and a parentId naming the tag it sits under; note is the frame\u2019s own description and thread. Use hub_manage action "knowledge" with a frameId or markId to read what people wrote on a frame. A markId is a tag id: a tag\u2019s id, parentId and threadRef come back literal when they have the shape the app mints, so they can be passed straight back; every other string value in the marks is wrapped as data, and so is an object key that is not a plain identifier.';
 var FRAME_MANAGE_INPUT_SCHEMA = {
   action: z10.enum(["list", "page", "get"]).describe(
-    "list the project\u2019s frames, read one page with marks, or read one frame"
+    "list the flow\u2019s frames, read one page with marks, or read one frame"
   ),
   projectId: z10.string().optional().describe(
     "Project ID. Optional: falls back to the default project when omitted."
   ),
+  flowId: z10.string().optional().describe(
+    'Flow ID (flow_...). Required for list, page and get: frames belong to a flow. Use flow_manage action "list" to find one.'
+  ),
   pageKey: z10.string().min(1).max(MAX_PAGE_KEY_CHARS).optional().describe(
     "The page as its frames address it (the `source.key` of a page frame, usually the page URL without query). Required for page."
   ),
@@ -2703,12 +2710,23 @@ var annotations9 = {
 };
 var FRAME_HINT_OPEN_PAGE_OR_GET = 'Use action "page" with a pageKey (a frame\u2019s source.key) to read a page with marks, or action "get" with a frameId.';
 var FRAME_HINT_NAMES_ARE_DOCUMENTATION = "Frame names are documentation; the marks inside a frame carry the meaning.";
-var FRAME_HINT_NONE_YET = "This project has no frames yet. Frames are drawn in Tag Mode or the app, not through this tool.";
+var FRAME_HINT_NONE_YET = "This flow has no frames yet. Frames are drawn in Tag Mode or the app, not through this tool.";
 var FRAME_HINT_MARK_SPACE = "Tag geometry is fractional: a rect is 0..1 of its frame, and an at is 0..1 of its parent tag\u2019s box, or of the frame for a root tag; a child frame sits inside its parent through placements[].rect.";
 var FRAME_HINT_READ_KNOWLEDGE = 'Use hub_manage action "knowledge" with frameId (and markId) to read what people wrote here. A markId is a tag id from these marks, and a tag\u2019s threadRef is the id of its thread entry there.';
 var FRAME_HINT_NONE_ON_PAGE = 'No frames on this page. Check the pageKey against the source.key values from action "list".';
 var FRAME_HINT_EXTENDS_BASE = "This frame extends another and stores only what it adds; read the base frame (extends) for the rest.";
 var FRAME_NOT_FOUND_HINT = 'Use action "list" or "page" to find frame ids.';
+var FRAME_FLOW_NOT_FOUND_HINT = 'Use flow_manage action "list" to find a live flow of the project.';
+function frameRefusalHint(error) {
+  switch (codeOf(error)) {
+    case "FLOW_NOT_FOUND":
+      return FRAME_FLOW_NOT_FOUND_HINT;
+    case "FRAME_NOT_FOUND":
+      return FRAME_NOT_FOUND_HINT;
+    default:
+      return errorHint(error, "frames", FRAME_NOT_FOUND_HINT);
+  }
+}
 var keepSourceAddress = (key) => key === "kind" || key === "key";
 function serializeLean(frame) {
   return {
@@ -2718,7 +2736,6 @@ function serializeLean(frame) {
     extends: frame.extends,
     source: redactNestedStrings(frame.source, { skip: keepSourceAddress }),
     origin: frame.origin,
-    flowId: frame.flowId,
     placements: frame.placements.map((placement) => ({
       id: placement.id,
       rect: placement.rect
@@ -2807,11 +2824,11 @@ async function frameManageHandler(client, rawInput) {
   if (!parsed.success) {
     return mcpError10(new Error(inputIssuesMessage(parsed.error)));
   }
-  const { action, projectId, pageKey, frameId } = parsed.data;
+  const { action, projectId, flowId, pageKey, frameId } = parsed.data;
   const validationError = validateActionInput(
     "frame_manage",
     action,
-    { pageKey, frameId },
+    { flowId, pageKey, frameId },
     FRAME_MANAGE_REQUIREMENTS
   );
   if (validationError) return mcpError10(new Error(validationError));
@@ -2822,8 +2839,10 @@ async function frameManageHandler(client, rawInput) {
     }
     switch (action) {
       case "list": {
+        assertParam(flowId, "flowId", "list");
         const { frames } = await client.listFrames({
-          projectId: resolvedProjectId
+          projectId: resolvedProjectId,
+          flowId
         });
         return mcpResult9(
           { frames: frames.map(serializeLean) },
@@ -2836,9 +2855,11 @@ async function frameManageHandler(client, rawInput) {
         );
       }
       case "page": {
+        assertParam(flowId, "flowId", "page");
         assertParam(pageKey, "pageKey", "page");
         const { frames } = await client.listPageFrames({
           projectId: resolvedProjectId,
+          flowId,
           pageKey
         });
         return mcpResult9(
@@ -2849,9 +2870,11 @@ async function frameManageHandler(client, rawInput) {
         );
       }
       case "get": {
+        assertParam(flowId, "flowId", "get");
         assertParam(frameId, "frameId", "get");
         const frame = await client.getFrame({
           projectId: resolvedProjectId,
+          flowId,
           frameId
         });
         return mcpResult9(
@@ -2863,7 +2886,7 @@ async function frameManageHandler(client, rawInput) {
       }
     }
   } catch (error) {
-    return mcpError10(error, errorHint(error, "frames", FRAME_NOT_FOUND_HINT));
+    return mcpError10(error, frameRefusalHint(error));
   }
 }
 function createFrameManageToolSpec(client) {
@@ -2941,7 +2964,7 @@ async function feedbackHandlerBody(client, input) {
     const isAnonymous = explicitAnonymous ?? anonymous ?? true;
     await client.submitFeedback(text, {
       anonymous: isAnonymous,
-      version: "4.7.2"
+      version: "4.8.0-next-1791441510508"
     });
     return mcpResult10({ ok: true });
   } catch (error) {
@@ -3733,7 +3756,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.7.2";
+var CLIENT_HEADER = "walkeros-mcp/4.8.0-next-1791441510508";
 function getPackageBaseUrl() {
   return process.env.WALKEROS_APP_URL || void 0;
 }
@@ -4991,7 +5014,7 @@ var SERVER_INSTRUCTIONS = `walkerOS is an open-source, privacy-first event data
 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
 16. \`hub_manage({ action: "releases", flowId: "..." })\` - read what changed across releases and why; \`release_get\` carries a server-computed diff, \`rationale_set\` records why
-17. \`frame_manage({ action: "page", pageKey: "..." })\` - read the frames of a page with their marks; read-only, edited in Tag Mode or the app
+17. \`frame_manage({ action: "page", flowId: "...", pageKey: "..." })\` - read the frames of a flow on one page with their marks; read-only, edited in Tag Mode or the app
 
 ## Architecture: Source \u2192 Collector \u2192 Destination(s)
 
@@ -5411,7 +5434,7 @@ var HttpToolClient = class {
   async checkContract() {
     return compareContract({
       baseUrl: this.appBaseUrl(),
-      client: { type: "mcp", version: "4.7.2" }
+      client: { type: "mcp", version: "4.8.0-next-1791441510508" }
     });
   }
   /** The live public OpenAPI document of `appBaseUrl()`, without a credential. */
@@ -5687,7 +5710,7 @@ var TOOL_DEFINITIONS = [
   {
     name: "flow_manage",
     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.",
+    description: "Manage walkerOS flows and their previews. List/get/create/update/delete/duplicate flows (deleting a flow deletes its frames too), or create/inspect/delete preview bundles for testing flow changes on live sites.",
     inputSchema: {
       action: z21.enum([
         "list",