@walkeros/mcp 4.7.2 → 4.8.0-next-1791496487198

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

@@ -211,8 +211,9 @@ import { mcpError } from "@walkeros/core";
 function inputIssuesMessage(error) {
   return error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
 }
-function parseToolInput(shape, raw) {
-  const parsed = z.object(shape).safeParse(raw ?? {});
+function parseToolInput(shape, raw, options = {}) {
+  const schema = options.strict ? z.strictObject(shape) : z.object(shape);
+  const parsed = schema.safeParse(raw ?? {});
   if (!parsed.success) {
     return {
       ok: false,
@@ -445,7 +446,7 @@ var FLOW_MANAGE_REQUIREMENTS = {
   preview_get: { required: ["flowId", "previewId"] },
   preview_create: {
     required: ["flowId"],
-    oneOf: [["flowName", "flowSettingsId"]]
+    oneOf: [["settingsName", "flowSettingsId"]]
   },
   preview_delete: { required: ["flowId", "previewId"] },
   preview_regrant: { required: ["flowId", "previewId"] }
@@ -502,13 +503,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 +799,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",
@@ -833,11 +838,11 @@ var inputSchema3 = {
   previewId: z4.string().optional().describe(
     "Preview ID (prv_...). Required for preview_get, preview_delete, and preview_regrant (all also require flowId)."
   ),
-  flowName: z4.string().optional().describe(
-    "Used by preview_create \u2014 provide one of flowName or flowSettingsId (preview_create also requires flowId)."
+  settingsName: z4.string().optional().describe(
+    "Settings name of a multi-settings flow (the `settings[].name` from flow_manage list). Used by preview_create: provide one of settingsName or flowSettingsId (preview_create also requires flowId)."
   ),
   flowSettingsId: z4.string().optional().describe(
-    "Used by preview_create \u2014 provide one of flowName or flowSettingsId (preview_create also requires flowId)."
+    "Used by preview_create: provide one of settingsName or flowSettingsId (preview_create also requires flowId)."
   ),
   source: z4.discriminatedUnion("kind", [
     z4.object({ kind: z4.literal("draft") }),
@@ -918,7 +923,7 @@ function createFlowManageToolSpec(client) {
   };
 }
 async function flowManageHandlerBody(client, input) {
-  const parsed = parseToolInput(inputSchema3, input);
+  const parsed = parseToolInput(inputSchema3, input, { strict: true });
   if (!parsed.ok) return parsed.error;
   const {
     action,
@@ -934,7 +939,7 @@ async function flowManageHandlerBody(client, input) {
     cursor,
     limit,
     previewId,
-    flowName,
+    settingsName,
     flowSettingsId,
     source,
     siteUrl,
@@ -944,7 +949,7 @@ async function flowManageHandlerBody(client, input) {
   const validationError = validateActionInput(
     "flow_manage",
     action ?? "",
-    { flowId, projectId, name, previewId, flowName, flowSettingsId },
+    { flowId, projectId, name, previewId, settingsName, flowSettingsId },
     FLOW_MANAGE_REQUIREMENTS
   );
   if (validationError) return mcpError4(new Error(validationError));
@@ -1140,7 +1145,7 @@ async function flowManageHandlerBody(client, input) {
         const preview = await client.createPreview({
           projectId: resolvedProjectId,
           flowId,
-          flowName,
+          flowName: settingsName,
           flowSettingsId,
           ...source ? { source } : {},
           ...siteUrl ? { siteUrl } : {}
@@ -1213,7 +1218,9 @@ function registerFlowManageTool(server, client) {
     {
       title: spec.title,
       description: spec.description,
-      inputSchema: spec.inputSchema,
+      // Strict, so a key the tool does not take is an input error naming that
+      // key rather than a key dropped without a word.
+      inputSchema: z4.strictObject(spec.inputSchema),
       annotations: spec.annotations
     },
     (args) => flowManageHandlerBody(client, args)
@@ -1276,7 +1283,7 @@ async function resolveDeploymentSlug(args) {
 
 // src/tools/deploy-manage.ts
 var TITLE4 = "Deploy Management";
-var DESCRIPTION4 = "Deploy walkerOS flows and manage deployments. deploy waits for the deployment to reach a terminal status by default (wait=true), with a 12-minute budget; pass wait=false to return immediately with the deployment id. A finished deployment carries its status and, on failure, an errorMessage with the user-facing reason; use the get action to re-read it. list supports cursor and limit for pagination. delete removes an active deployment. For get and delete 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.";
+var DESCRIPTION4 = "Deploy walkerOS flows and manage deployments. deploy waits for the deployment to reach a terminal status by default (wait=true), up to 12 minutes on the local door and up to 10 minutes on the hosted door; pass wait=false to return immediately with the deployment id. A finished deployment carries its status and, on failure, an errorMessage with the user-facing reason; use the get action to re-read it. list supports cursor and limit for pagination. delete removes an active deployment. For get and delete 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.";
 var DEPLOYMENT_STATUSES = {
   idle: true,
   deploying: true,
@@ -1304,10 +1311,10 @@ var inputSchema4 = {
   type: z5.enum(membersOf(DEPLOYMENT_TYPES)).optional().describe("Deployment type filter for list."),
   status: z5.enum(membersOf(DEPLOYMENT_STATUSES)).optional().describe("Status filter for list."),
   wait: z5.boolean().optional().describe(
-    "Wait for the deployment to reach a terminal status (default true), with a 12-minute budget. Set false to return the deployment id immediately. Only used with deploy action."
+    "Wait for the deployment to reach a terminal status (default true): up to 12 minutes on the local door, up to 10 minutes on the hosted door. Set false to return the deployment id immediately. Only used with deploy action."
   ),
-  flowName: z5.string().optional().describe(
-    "Flow name for multi-settings flows. Only used with deploy action."
+  settingsName: z5.string().optional().describe(
+    "Settings name of a multi-settings flow (the `settings[].name` from flow_manage list). Only used with deploy action."
   ),
   cursor: z5.string().optional().describe(
     "Pagination cursor from a previous list response. Only used with the list action."
@@ -1376,7 +1383,7 @@ function createDeployManageToolSpec(client) {
   };
 }
 async function deployManageHandlerBody(client, input) {
-  const parsed = parseToolInput(inputSchema4, input);
+  const parsed = parseToolInput(inputSchema4, input, { strict: true });
   if (!parsed.ok) return parsed.error;
   const {
     action,
@@ -1386,7 +1393,7 @@ async function deployManageHandlerBody(client, input) {
     type,
     status,
     wait,
-    flowName,
+    settingsName,
     cursor,
     limit
   } = parsed.data;
@@ -1405,7 +1412,7 @@ async function deployManageHandlerBody(client, input) {
           flowId,
           projectId,
           wait: wait ?? true,
-          flowName
+          flowName: settingsName
         });
         const appUrl = deploymentUrl(client, projectId, result);
         return mcpResult4(withAppUrl(redactDisplayNames(result), appUrl), {
@@ -1478,7 +1485,9 @@ function registerDeployTool(server, client) {
     {
       title: spec.title,
       description: spec.description,
-      inputSchema: spec.inputSchema,
+      // Strict, so a key the tool does not take is an input error naming that
+      // key: a dropped settings key would deploy as if no settings were named.
+      inputSchema: z5.strictObject(spec.inputSchema),
       annotations: spec.annotations
     },
     (args) => deployManageHandlerBody(client, args)
@@ -2680,14 +2689,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 +2715,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 +2741,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 +2829,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 +2844,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 +2860,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 +2875,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 +2891,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 +2969,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-1791496487198"
     });
     return mcpResult10({ ok: true });
   } catch (error) {
@@ -3733,7 +3761,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-1791496487198";
 function getPackageBaseUrl() {
   return process.env.WALKEROS_APP_URL || void 0;
 }
@@ -4991,7 +5019,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 +5439,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-1791496487198" }
     });
   }
   /** The live public OpenAPI document of `appBaseUrl()`, without a credential. */
@@ -5687,7 +5715,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",
@@ -5711,7 +5739,7 @@ var TOOL_DEFINITIONS = [
       order: z21.enum(["asc", "desc"]).optional(),
       includeDeleted: z21.boolean().optional(),
       previewId: z21.string().optional(),
-      flowName: z21.string().optional(),
+      settingsName: z21.string().optional(),
       flowSettingsId: z21.string().optional(),
       siteUrl: z21.string().optional()
     },
@@ -5734,7 +5762,7 @@ var TOOL_DEFINITIONS = [
       type: z21.enum(["web", "server"]).optional(),
       status: z21.string().optional(),
       wait: z21.boolean().optional(),
-      flowName: z21.string().optional()
+      settingsName: z21.string().optional()
     },
     annotations: {
       readOnlyHint: false,