@wootsup/mcp 0.1.0 → 0.4.0

package/dist/modules/apimapper/flows.js

@@ -1,8 +1,11 @@
 import { z } from "zod";
-import { formatResult, tableResult, errorResult, readOnly, creating, mutating, destructive, createProgressReporter, elicitChoice, } from "@getimo/mcp-toolkit";
+import { formatResult, tableResult, errorResult, readOnly, creating, mutating, destructive, createProgressReporter, } from "@getimo/mcp-toolkit";
 import { request, hintFor } from "./client.js";
+import { restErrorResult } from "./tool-result.js";
 import { toRows } from "./types.js";
-import { nodeSchema, edgeSchema, filterByNameQuery } from "./node-schema.js";
+import { nodeSchema, edgeSchema, ensureEdgeIds, filterByNameQuery } from "./node-schema.js";
+import { autoLayoutNodes } from "./auto-layout.js";
+import { withOverflowFooter } from "./list-footer.js";
 import { unwrapEntity } from "./envelope.js";
 import { ambiguityFallbackError, } from "./elicitation.js";
 import { buildFlowVisualization, SIDECAR_RESPONSE_MAX_CHARS, } from "./render/sidecar.js";
@@ -11,13 +14,15 @@ import { FLOW_TABLE_COLUMNS, FLOW_COMPACT_COLUMNS, FLOW_LIST_NEXT_STEPS, isFlowC
  * Register the flow CRUD + compile + detect-schema + trace + export/import
  * tools.
  *
- * @param server      the tool registrar (essentials forward, rest captured).
- * @param elicitation optional elicitation capability (the real McpServer, or
- *   any `{ server: { elicitInput } }`). Supplied only by the host wiring in
- *   index.ts. When omitted, `flow_compile` falls back to a structured error
- *   on genuine flow ambiguity instead of prompting.
+ * Chat-first disambiguation (decision 2026-06-15): on genuine flow ambiguity
+ * `flow_compile` returns a structured candidate-list error (the assistant
+ * asks in plain chat) rather than driving the native elicitation picker. The
+ * picker is reserved for OAuth authorization (credentials.ts), so this module
+ * no longer takes an elicitation capability.
+ *
+ * @param server the tool registrar (essentials forward, rest captured).
  */
-export function registerFlowTools(server, elicitation) {
+export function registerFlowTools(server) {
     // ── apimapper_flow_list ────────────────────────────────────────────
     server.registerTool("apimapper_flow_list", {
         title: "List Flows",
@@ -49,12 +54,7 @@ export function registerFlowTools(server, elicitation) {
     }, async ({ source, compiled, limit, name_query }) => {
         const r = await request("/flows");
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow list failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { source, compiled, limit, name_query },
-            });
+            return restErrorResult(r, { source, compiled, limit, name_query }, { message: "flow list failed" });
         }
         let items = Array.isArray(r.data?.flows) ? r.data.flows : [];
         // `is_compiled` is derived from the REST shape (compiledAt / compiled[])
@@ -82,13 +82,20 @@ export function registerFlowTools(server, elicitation) {
             map: mapFlowRow,
             compactMap: compactFlowRow,
             header: (n) => `${n} flows`,
-            footer: FLOW_LIST_NEXT_STEPS,
+            // Minor (2026-06-10): overflow-aware footer (see list-footer.ts).
+            footer: withOverflowFooter(FLOW_LIST_NEXT_STEPS, items.length, "flows"),
         });
     });
     // ── apimapper_flow_get ─────────────────────────────────────────────
     server.registerTool("apimapper_flow_get", {
         title: "Get Flow",
-        description: "Fetch full flow definition (nodes, edges, viewport, compiled artifact)." +
+        description: "Get the full definition of one flow by ID (nodes, edges, viewport, and the " +
+            "compiled artifact). Use to inspect or debug a flow's graph before editing " +
+            "nodes/edges, changing a merge strategy, or re-compiling. " +
+            "Keywords: get flow, flow detail, inspect flow, show graph, nodes and edges, by ID. " +
+            "When NOT to use: to enumerate all flows use apimapper_flow_list; to change the " +
+            "graph use apimapper_flow_update then apimapper_flow_compile; to see the last " +
+            "run's per-step timing use apimapper_flow_trace." +
             "\n\nExample:\n  apimapper_flow_get({ id: 'flow_Z2fLg70M84' })",
         inputSchema: {
             id: z.string().describe('Flow ID (e.g., "flow_aCfOEpwCtVZnPFwPOwO61"). Use apimapper_flow_list.'),
@@ -99,12 +106,7 @@ export function registerFlowTools(server, elicitation) {
         // `{success:true, flow:{…}}`. Audit: F-A2-01.
         const r = await request(`/flows/${encodeURIComponent(id)}`);
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow get failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id },
-            });
+            return restErrorResult(r, { id }, { message: "flow get failed" });
         }
         const flow = unwrapEntity(r.data, "flow");
         if (!flow || Object.keys(flow).length === 0) {
@@ -127,7 +129,7 @@ export function registerFlowTools(server, elicitation) {
         title: "Create Flow",
         description: "Create a new flow with full nodes + edges JSON. " +
             "For declarative multi-source flow creation use apimapper_flow_setup_with_sources instead." +
-            "\n\nExample:\n  apimapper_flow_create({ name: 'My Pexels Gallery', nodes: [{ id: 'src1', type: 'source' }, { id: 'out1', type: 'output' }], edges: [{ source: 'src1', target: 'out1' }] })",
+            "\n\nExample:\n  apimapper_flow_create({ name: 'My Pexels Gallery', nodes: [{ id: 'src1', type: 'source', position: { x: 0, y: 0 }, data: { connectionId: 'con_abc123' } }, { id: 'out1', type: 'output-yootheme', position: { x: 400, y: 0 }, data: { name: 'My Pexels Gallery' } }], edges: [{ source: 'src1', target: 'out1' }] })",
         inputSchema: {
             name: z.string().min(1).describe('Flow name (appears in YOOtheme dropdown)'),
             description: z.string().optional().describe("Optional description"),
@@ -149,22 +151,47 @@ export function registerFlowTools(server, elicitation) {
                 .object({ x: z.number(), y: z.number(), zoom: z.number() })
                 .optional()
                 .describe('React-Flow viewport (e.g., {"x":0,"y":0,"zoom":1})'),
+            // Phase 2.7 (change protocol): an optional AI one-liner recorded
+            // alongside the create. The action is IMPLICIT (`flow.created`) so the
+            // handler defaults it — only `summary` is needed here. Threaded into
+            // the POST body as `change: { summary }` (conditional-spread: absent
+            // when omitted, so the body stays byte-identical to today).
+            summary: z
+                .string()
+                .max(280)
+                .optional()
+                .describe("Optional one-line summary of this change for the flow's change history " +
+                '(e.g., "Created a Pexels gallery flow with 2 sources").'),
         },
         annotations: creating({ title: "Create Flow", openWorld: true }),
-    }, async (input) => {
+    }, async ({ summary, ...input }) => {
+        // F5 (2026-06-09): stamp a stable id on any id-less edge BEFORE POST. The
+        // schema marks edge.id optional (the AI legitimately omits it), but the
+        // React-Flow runtime + backend graph validator key edges by id and reject
+        // an id-less edge with a misleading "connectivity" error. ensureEdgeIds
+        // makes both layers accept the graph. buildFlowGraph already does this for
+        // its synthetic graphs; this closes the gap for hand-authored flows.
+        // Task X: tidy the graph on every AI write — re-flow node positions into a
+        // clean layered left-to-right grid (orphans trail in their own column).
+        // AI-path only; a human's manual positions (saved by the admin-ui
+        // autosave) are never touched.
+        const payload = {
+            ...input,
+            nodes: autoLayoutNodes(input.nodes, input.edges),
+            edges: ensureEdgeIds(input.edges),
+            // Phase 2.7 — implicit action (`flow.created`), so only `summary` is
+            // attached; the handler defaults the action. Conditional-spread keeps
+            // the body byte-identical to today when no summary is supplied.
+            ...(summary !== undefined ? { change: { summary } } : {}),
+        };
         // PHP fromControllerResponse(_, 'flow', 201) → {success, flow:{…}}.
         // Audit: F-A2-02.
         const r = await request("/flows", {
             method: "POST",
-            body: JSON.stringify(input),
+            body: JSON.stringify(payload),
         });
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow create failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { name: input.name, node_count: input.nodes.length },
-            });
+            return restErrorResult(r, { name: input.name, node_count: input.nodes.length }, { message: "flow create failed" });
         }
         const flow = unwrapEntity(r.data, "flow");
         // Sidecar: flow_create always has input.nodes + input.edges
@@ -172,8 +199,8 @@ export function registerFlowTools(server, elicitation) {
         // APIMAPPER_AUTO_VISUALIZE_FLOWS="false". Additive + defensive —
         // a render failure returns null and is omitted silently.
         const viz = buildFlowVisualization({
-            nodes: input.nodes,
-            edges: input.edges,
+            nodes: payload.nodes,
+            edges: payload.edges,
             id: flow?.id,
             name: flow?.name,
         });
@@ -188,7 +215,7 @@ export function registerFlowTools(server, elicitation) {
             // (array, even if single-element) matches the structured
             // next-step convention used by the list-result footers and the
             // detailResult builders. Flat `next: string` was the holdout.
-            next_steps: ["Call apimapper_flow_compile to publish to YOOtheme."],
+            next_steps: ["Publish to YOOtheme via apimapper_flow_full_recompile_publish (or apimapper_advanced({ tool: \"apimapper_flow_compile\" }))."],
         }, false, 
         // Headroom for the sidecar — see SIDECAR_RESPONSE_MAX_CHARS.
         { maxChars: SIDECAR_RESPONSE_MAX_CHARS });
@@ -197,49 +224,133 @@ export function registerFlowTools(server, elicitation) {
     server.registerTool("apimapper_flow_update", {
         title: "Update Flow",
         description: "Update flow fields. Use to modify nodes/edges (e.g., toggle merge.strategy, change joinKey). " +
-            "After update, call apimapper_flow_compile." +
-            "\n\nExample:\n  apimapper_flow_update({ id: 'flow_Z2fLg70M84', name: 'My Pexels Gallery (v2)' })",
+            "After update, recompile via apimapper_flow_full_recompile_publish." +
+            "\n\nExample:\n  apimapper_flow_update({ id: 'flow_Z2fLg70M84', patch: { name: 'My Pexels Gallery (v2)' } })",
         inputSchema: {
             id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
             patch: z
                 .record(z.string(), z.unknown())
                 .describe('Fields to patch (e.g., {"nodes":[...updated nodes...]} or {"name":"Renamed"})'),
+            // Phase 2.7 (change protocol): flow_update has NO implicit action — the
+            // edit could be anything, so the caller names it explicitly. `action`
+            // is a verb-ish string (e.g. "node.added", "filter.set",
+            // "merge.changed"); `detail` is optional structured context.
+            change: z
+                .object({
+                action: z
+                    .string()
+                    .describe('What changed, e.g. "node.added" / "filter.set" / "merge.changed".'),
+                detail: z
+                    .record(z.string(), z.unknown())
+                    .optional()
+                    .describe('Optional structured context (e.g. { node_id: "filter1" }).'),
+            })
+                .optional()
+                .describe("Optional change-protocol record for the flow's change history. Provide an " +
+                "explicit `action` (this tool has no implicit one)."),
+            // Phase 2.7 — optional AI one-liner alongside the explicit action.
+            summary: z
+                .string()
+                .max(280)
+                .optional()
+                .describe('Optional one-line summary of this change (e.g., "Added a price filter > 10").'),
         },
         annotations: mutating({ title: "Update Flow", openWorld: true }),
-    }, async ({ id, patch }) => {
+    }, async ({ id, patch, change, summary }) => {
+        // F5 (2026-06-09): when the patch carries an `edges` array, stamp a stable
+        // id on any id-less edge before PUT — same fix as flow_create. Done only
+        // when `patch.edges` is actually an array so a name-only / metadata-only
+        // patch is forwarded byte-for-byte (no `edges` key injected).
+        const patchObj = (patch && typeof patch === "object" ? patch : {});
+        const requestPatch = Array.isArray(patchObj.edges)
+            ? {
+                ...patchObj,
+                // Task X: a graph-touching update (nodes + edges) is re-laid-out so
+                // the AI's edit lands tidy (orphans included). A node-less /
+                // edges-only patch is untouched. AI-path only — never the human
+                // autosave path, so manual positions survive.
+                ...(Array.isArray(patchObj.nodes)
+                    ? {
+                        nodes: autoLayoutNodes(patchObj.nodes, patchObj.edges),
+                    }
+                    : {}),
+                edges: ensureEdgeIds(patchObj.edges),
+            }
+            : patch;
+        // Phase 2.7 (change protocol): attach the explicit change record + the
+        // optional summary as a sibling `change` key on the PUT body. Built
+        // conditionally so a caller that supplied neither sends a body
+        // byte-identical to today (no empty `change` key injected). When only
+        // `summary` is given (no explicit action), the handler defaults the
+        // action — mirrors the implicit-action tools.
+        const changePayload = change !== undefined || summary !== undefined
+            ? {
+                ...(change ?? {}),
+                ...(summary !== undefined ? { summary } : {}),
+            }
+            : undefined;
+        const requestBody = changePayload !== undefined
+            ? { ...requestPatch, change: changePayload }
+            : requestPatch;
         // PHP fromControllerResponse(_, 'flow') → {success, flow:{…}}. On 409 the
         // body shape is {currentVersion, error, code}. Audit: F-A2-03.
         const r = await request(`/flows/${encodeURIComponent(id)}`, {
             method: "PUT",
-            body: JSON.stringify(patch),
+            body: JSON.stringify(requestBody),
         });
         if (!r.success) {
             // Surface currentVersion (when present on 409) so the agent can
             // re-read + retry without a separate fetch.
             const envelope = (r.data && typeof r.data === "object" ? r.data : {});
             const currentVersion = typeof envelope.currentVersion === "number" ? envelope.currentVersion : undefined;
-            return errorResult({
-                message: r.error ?? "flow update failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id, ...(currentVersion !== undefined ? { currentVersion } : {}) },
-            });
+            return restErrorResult(r, { id, ...(currentVersion !== undefined ? { currentVersion } : {}) }, { message: "flow update failed" });
         }
         const flow = unwrapEntity(r.data, "flow");
         // Sidecar: flow_update's patch is a generic record. The
         // visualization is CONDITIONAL — render only when the patch
         // carries a full graph (both nodes and edges as arrays). A
-        // name-only / metadata-only patch has no graph to draw.
-        const patchObj = (patch && typeof patch === "object" ? patch : {});
+        // name-only / metadata-only patch has no graph to draw. Use the
+        // id-stamped edges (requestPatch.edges) so the diagram matches what
+        // was actually PUT.
         const patchHasGraph = Array.isArray(patchObj.nodes) && Array.isArray(patchObj.edges);
+        // F148 — a patch that touches `nodes` can CHANGE THE OUTPUT SCHEMA (e.g.
+        // a transform expression that derives new fields). Those new fields are
+        // NOT bindable in the YOOtheme Builder until the flow is recompiled — and
+        // an already-bound element keeps the OLD field set until re-bound. The
+        // F41+F44 next-steps below surface that schema→recompile→re-bind chain.
         const viz = patchHasGraph
             ? buildFlowVisualization({
                 nodes: patchObj.nodes,
-                edges: patchObj.edges,
+                edges: requestPatch.edges,
                 id: flow?.id,
                 name: flow?.name,
             })
             : null;
+        // F41 + F44 + F148: the next-step guidance must be
+        //   (a) gateway-SAFE — `apimapper_flow_compile` is gateway-only (not in
+        //       tools/list); a bare reference returns "No such tool". The
+        //       recompile-publish tool IS essential, so point at it.
+        //   (b) schema-change-AWARE — when the patch carried `nodes`, the output
+        //       schema may have changed (new/renamed derived fields). Those
+        //       fields are invisible to apimapper_yootheme_binding_for_flow until
+        //       a recompile-publish, and any already-bound YOOtheme element keeps
+        //       the OLD field set and must be re-bound against the fresh schema.
+        const patchTouchedGraph = Array.isArray(patchObj.nodes);
+        let nextSteps;
+        if (patchTouchedGraph) {
+            nextSteps = [
+                "Graph changed — run apimapper_flow_full_recompile_publish to recompile and re-register the YOOtheme source.",
+                "Schema may have changed: new/renamed fields are invisible to apimapper_yootheme_binding_for_flow until that recompile. After it, re-read bindings and RE-BIND the YOOtheme element (field_mappings is a full replace) — the old binding keeps the previous field set.",
+            ];
+        }
+        else if (flow?.is_compiled) {
+            nextSteps = [
+                "Metadata changed on a compiled flow — recompile with apimapper_flow_full_recompile_publish (or apimapper_advanced({ tool: \"apimapper_flow_compile\", arguments: { id } }), which is gateway-only).",
+            ];
+        }
+        else {
+            nextSteps = [];
+        }
         return formatResult({
             updated: true,
             id: flow?.id,
@@ -250,9 +361,7 @@ export function registerFlowTools(server, elicitation) {
             // F-3.1 (Pass-1 consolidation): IA-10 uniformity — flat next has
             // been migrated to next_steps[]. Empty array when no recompile is
             // needed (so the key shape stays uniform across all paths).
-            next_steps: flow?.is_compiled
-                ? ["Compile likely invalidated — call apimapper_flow_compile."]
-                : [],
+            next_steps: nextSteps,
         }, false, 
         // Headroom for the (conditional) sidecar — see SIDECAR_RESPONSE_MAX_CHARS.
         { maxChars: SIDECAR_RESPONSE_MAX_CHARS });
@@ -277,6 +386,26 @@ export function registerFlowTools(server, elicitation) {
             // Audit: F-A2-04.
             const preview = await request(`/flows/${encodeURIComponent(id)}`);
             const flow = preview.success ? unwrapEntity(preview.data, "flow") : undefined;
+            // F204 — ownership posture. The flow carries `created_by` (the kid of
+            // the MCP key that created it; null for cookie / Admin-UI flows). A
+            // write-scoped key may delete ONLY a flow it created; a null-owned flow
+            // requires the admin scope. The client can't compare its own kid (the
+            // token is opaque here), so this is an INFORMATIONAL signal — the server
+            // enforces it and returns a 403 (insufficient_scope_ownership) on a real
+            // mismatch (surfaced by restErrorResult's scopeAware path below).
+            const ownership = flow && flow.created_by != null
+                ? {
+                    can_delete: "owner_or_admin",
+                    delete_reason: "A write-scope key can delete this flow only if it created it " +
+                        `(created_by: ${flow.created_by}); an admin-scope key deletes any flow.`,
+                }
+                : flow
+                    ? {
+                        can_delete: "admin_only",
+                        delete_reason: "This flow has no owner kid (created via the dashboard or before " +
+                            "ownership tracking), so deleting it requires the admin scope.",
+                    }
+                    : null;
             return formatResult({
                 preview: true,
                 warning: "DESTRUCTIVE — Flow delete cannot be undone. Sources disappear from YOOtheme.",
@@ -287,19 +416,19 @@ export function registerFlowTools(server, elicitation) {
                         node_count: flow.node_count,
                         is_compiled: flow.is_compiled,
                         node_types: flow.node_types,
+                        created_by: flow.created_by ?? null,
                     }
                     : { id, note: "could not preview — id may not exist" },
+                ...(ownership ?? {}),
                 instruction: "Ask user to confirm, then call again with confirm: true.",
             });
         }
         const r = await request(`/flows/${encodeURIComponent(id)}`, { method: "DELETE" });
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow delete failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id },
-            });
+            // F6 (2026-06-09): a 403 here means the MCP key lacks the admin scope
+            // delete requires — NOT that the key is invalid/revoked. scopeAware
+            // swaps the generic key-recovery walkthrough for a scope-upgrade hint.
+            return restErrorResult(r, { id }, { message: "flow delete failed", scopeAware: true });
         }
         return formatResult({ deleted: true, id }, false, { maxChars: 1500 });
     });
@@ -318,9 +447,19 @@ export function registerFlowTools(server, elicitation) {
                 .optional()
                 .describe("Flow ID. Use apimapper_flow_list to find. Omit to resolve automatically " +
                 "when the install has a single flow."),
+            // Phase 2.7 (change protocol): compile = publish, so the action is
+            // IMPLICIT (`flow.published`) — only `summary` is needed; the handler
+            // defaults the action. Threaded into the POST body as
+            // `change: { summary }` (the compile POST otherwise has no body).
+            summary: z
+                .string()
+                .max(280)
+                .optional()
+                .describe('Optional one-line summary of this publish for the change history ' +
+                '(e.g., "Published the gallery after adding a city filter").'),
         },
         annotations: mutating({ title: "Compile Flow", openWorld: true }),
-    }, async ({ id }, extra) => {
+    }, async ({ id, summary }, extra) => {
         // W3.5 — coarse progress side-channel. `null` when the caller sent no
         // progressToken; `progress?.report(...)` then no-ops.
         const progress = extra ? createProgressReporter(extra) : null;
@@ -333,19 +472,14 @@ export function registerFlowTools(server, elicitation) {
         if (!resolvedId) {
             const lr = await request("/flows");
             if (!lr.success) {
-                return errorResult({
-                    message: lr.error ?? "flow lookup failed",
-                    code: lr.errorCode ?? (lr.status ? String(lr.status) : undefined),
-                    suggestion: hintFor(lr.errorCode),
-                    details: {},
-                });
+                return restErrorResult(lr, {}, { message: "flow lookup failed" });
             }
             const flows = Array.isArray(lr.data?.flows) ? lr.data.flows : [];
             if (flows.length === 0) {
                 return errorResult({
                     message: "No flows exist to compile.",
                     code: "flow_not_found",
-                    suggestion: "Create one with apimapper_flow_create, then compile it.",
+                    suggestion: 'Create + publish one in a single call via apimapper_flow_setup_with_sources, or build raw via apimapper_advanced({ tool: "apimapper_flow_create" }).',
                     details: {},
                 });
             }
@@ -353,22 +487,21 @@ export function registerFlowTools(server, elicitation) {
                 resolvedId = flows[0].id;
             }
             else {
+                // Chat-first disambiguation (decision 2026-06-15): skip the native
+                // elicitation picker (clunky collapsed TUI in some hosts) and
+                // return the structured candidate-list error directly. The
+                // `candidates` carry id+label, so the assistant sees the flow names
+                // and asks the user in plain chat which flow to compile.
                 const candidates = flows.map((f) => ({
                     id: f.id,
                     label: f.name,
                 }));
-                const picked = elicitation
-                    ? await elicitChoice(elicitation, "Several flows exist. Pick the flow to compile.", candidates.map((c) => c.id))
-                    : null;
-                if (picked === null) {
-                    return ambiguityFallbackError({
-                        code: "flow_ambiguous",
-                        paramName: "id",
-                        what: "flows",
-                        candidates,
-                    });
-                }
-                resolvedId = picked;
+                return ambiguityFallbackError({
+                    code: "flow_ambiguous",
+                    paramName: "id",
+                    what: "flows",
+                    candidates,
+                });
             }
         }
         await progress?.report(0, 1, "Compiling flow…");
@@ -376,14 +509,18 @@ export function registerFlowTools(server, elicitation) {
         // surfaced via HandlerResult::error(), not inside the 200 body. Audit:
         // F-A2-05 — the previous `errors[]` + `is_compiled===false` branch was
         // dead code.
-        const r = await request(`/flows/${encodeURIComponent(resolvedId)}/compile`, { method: "POST" });
+        // Phase 2.7 — implicit action (`flow.published`). Attach `change:
+        // { summary }` only when a summary was supplied; otherwise the compile
+        // POST carries no body, exactly as before.
+        const r = await request(`/flows/${encodeURIComponent(resolvedId)}/compile`, summary !== undefined
+            ? {
+                method: "POST",
+                body: JSON.stringify({ change: { summary } }),
+                headers: { "Content-Type": "application/json" },
+            }
+            : { method: "POST" });
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow compile failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id: resolvedId },
-            });
+            return restErrorResult(r, { id: resolvedId }, { message: "flow compile failed" });
         }
         await progress?.report(1, 1, "Flow compiled");
         const dataObj = r.data && typeof r.data === "object" ? r.data : {};
@@ -401,13 +538,31 @@ export function registerFlowTools(server, elicitation) {
     server.registerTool("apimapper_flow_detect_schema", {
         title: "Detect Flow Schema",
         description: "Re-detect/refresh the output schema by sampling the upstream API. " +
-            "Use after upstream endpoint changes to surface new fields in the YOOtheme Builder." +
-            "\n\nExample:\n  apimapper_flow_detect_schema({ id: 'flow_Z2fLg70M84' })",
+            "Use after upstream endpoint changes to surface new fields in the YOOtheme Builder. " +
+            "For library-template connections that carry `{{placeholder}}` substitutions in their " +
+            "endpoint path (Google Sheets `{{spreadsheet_id}}`/`{{range}}`, Calendly `{{user_uri}}`, " +
+            "etc.), pass `template_fields` to override or supply the values at detect-time — " +
+            "mirrors the `apimapper_connection_data` contract." +
+            "\n\nExample:\n  apimapper_flow_detect_schema({ id: 'flow_Z2fLg70M84' })" +
+            "\n  apimapper_flow_detect_schema({ id: 'flow_X', template_fields: { spreadsheet_id: '1abc', range: 'Sheet1!A:G' } })",
         inputSchema: {
             id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
+            endpoint: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Override the source node\'s endpoint selection (e.g. "Get Values"). ' +
+                "Empty-string and whitespace-only values are rejected at the schema boundary."),
+            template_fields: z
+                .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+                .optional()
+                .describe('Override values for `{{placeholder}}` substitutions in the endpoint URL ' +
+                '(e.g. { spreadsheet_id: "1abc", range: "Sheet1!A:G" }). Partial merge: ' +
+                "caller values win, persisted values for keys not mentioned here survive. " +
+                "Wave-12 F3 — restores parity with apimapper_connection_data."),
         },
         annotations: mutating({ title: "Detect Flow Schema", openWorld: true }),
-    }, async ({ id }, extra) => {
+    }, async ({ id, endpoint, template_fields }, extra) => {
         // W3.5 — coarse progress side-channel. `null` when the caller sent no
         // progressToken; `progress?.report(...)` then no-ops.
         const progress = extra ? createProgressReporter(extra) : null;
@@ -417,15 +572,28 @@ export function registerFlowTools(server, elicitation) {
         // H-2 fix (2026-05-27): backend now persists detected schema onto the
         // output node so the next compile finds non-empty fields. `persisted`
         // flag surfaces whether the write actually happened.
+        // Wave-12 F3 (Cold-AI #6, 2026-05-31): `endpoint` + `template_fields`
+        // now thread through to the PHP handler as sourceContext, restoring
+        // contract symmetry with apimapper_connection_data so library-template
+        // flows (Google Sheets etc.) can substitute URL placeholders at
+        // detect-time.
         // Audit: F-A2-06.
-        const r = await request(`/flows/${encodeURIComponent(id)}/detect-schema`, { method: "POST" });
+        const body = {};
+        if (endpoint !== undefined)
+            body.endpoint = endpoint;
+        if (template_fields !== undefined)
+            body.template_fields = template_fields;
+        const r = await request(`/flows/${encodeURIComponent(id)}/detect-schema`, {
+            method: "POST",
+            ...(Object.keys(body).length > 0
+                ? {
+                    body: JSON.stringify(body),
+                    headers: { "Content-Type": "application/json" },
+                }
+                : {}),
+        });
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow detect-schema failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id },
-            });
+            return restErrorResult(r, { id }, { message: "flow detect-schema failed" });
         }
         await progress?.report(1, 1, "Schema detected");
         const fields = Array.isArray(r.data?.schema?.fields) ? r.data.schema.fields : [];
@@ -454,21 +622,20 @@ export function registerFlowTools(server, elicitation) {
         title: "Get Flow Execution Trace",
         description: "Fetch the execution trace from the last run (timing per step, item counts, errors). " +
             "Useful for debugging slow flows or incorrect outputs." +
-            "\n\nExample:\n  apimapper_flow_trace({ id: 'flow_Z2fLg70M84' })",
+            // F213: gateway-only tool — show the call routed THROUGH the read
+            // gateway so the first live invocation doesn't fail invalid_arguments.
+            "\n\nExample (gateway-routed):\n  apimapper_advanced_read({ tool: \"apimapper_flow_trace\", arguments: { id: \"flow_Z2fLg70M84\" } })",
         inputSchema: {
             id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
         },
         annotations: readOnly({ title: "Trace Flow", openWorld: true }),
     }, async ({ id }) => {
-        // PHP success body: {trace: {steps: [...], total_ms}}. Audit: F-A2-07.
+        // PHP success body: {trace: {steps: [...], totalDuration}}. The native
+        // TraceService key is `totalDuration` (ms, float); `total_ms` is kept as
+        // a back-compat alias for any older backend shape. Audit: F-A2-07 / F185.
         const r = await request(`/flows/${encodeURIComponent(id)}/trace`);
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow trace failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id },
-            });
+            return restErrorResult(r, { id }, { message: "flow trace failed" });
         }
         const trace = r.data?.trace;
         const steps = Array.isArray(trace?.steps) ? trace.steps : [];
@@ -476,7 +643,10 @@ export function registerFlowTools(server, elicitation) {
         // chronological event timeline (display="event-timeline"). The step
         // cap is preserved (50) so a pathological trace cannot bloat the
         // response. buildFlowTraceTimeline does the defensive field reads.
-        return buildFlowTraceTimeline(id, steps.slice(0, 50), trace?.total_ms);
+        const totalMs = typeof trace?.totalDuration === "number"
+            ? trace.totalDuration
+            : trace?.total_ms;
+        return buildFlowTraceTimeline(id, steps.slice(0, 50), totalMs);
     });
     // ── apimapper_flow_export ──────────────────────────────────────────
     // F-24 (W1.13): the export bundle contains connection REFERENCES only —
@@ -512,12 +682,7 @@ export function registerFlowTools(server, elicitation) {
         // belt-and-braces pattern at credentials.ts (credential_list / get).
         const r = await request(`/flows/${encodeURIComponent(id)}/export`, {}, { sanitize: true });
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow export failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id },
-            });
+            return restErrorResult(r, { id }, { message: "flow export failed" });
         }
         const envelope = (r.data && typeof r.data === "object" ? r.data : {});
         const bundle = envelope.data ?? envelope.export ?? envelope;
@@ -546,12 +711,7 @@ export function registerFlowTools(server, elicitation) {
         // Audit: F-A2-09.
         const r = await request("/flows/import/validate", { method: "POST", body: JSON.stringify(bundle) });
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow import-validate failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: {},
-            });
+            return restErrorResult(r, {}, { message: "flow import-validate failed" });
         }
         // W3.1 — detailResult: the validation result is a flat envelope
         // ({valid, flowName, exportedFrom, connectionReferences}). The
@@ -600,12 +760,7 @@ export function registerFlowTools(server, elicitation) {
             body: JSON.stringify(body),
         });
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "flow import failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { rename_to },
-            });
+            return restErrorResult(r, { rename_to }, { message: "flow import failed" });
         }
         const flow = unwrapEntity(r.data, "flow");
         return formatResult({ imported: true, id: flow?.id, name: flow?.name }, false, { maxChars: 2000 });