@wootsup/mcp 0.3.0 → 0.4.0

package/dist/modules/apimapper/connections.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { formatResult, tableResult, errorResult, readOnly, creating, mutating, destructive, pickFields, createProgressReporter, elicitChoice, } from "@getimo/mcp-toolkit";
+import { formatResult, tableResult, errorResult, readOnly, creating, mutating, destructive, pickFields, createProgressReporter, } from "@getimo/mcp-toolkit";
 import { request, hintFor, WP_BASE, WP_USER, authConfigured } from "./client.js";
 import { restErrorResult } from "./tool-result.js";
 import { toRows } from "./types.js";
@@ -7,7 +7,8 @@ import { unwrapEntity } from "./envelope.js";
 import { ambiguityFallbackError, } from "./elicitation.js";
 import { fetchWithTimeout } from "./diagnose.js";
 import { filterByNameQuery } from "./node-schema.js";
-import { CONNECTION_TABLE_COLUMNS, CONNECTION_COMPACT_COLUMNS, CONNECTION_LIST_NEXT_STEPS, RESOURCE_TABLE_COLUMNS, mapConnectionRow, compactConnectionRow, mapResourceRow, buildConnectionDetail, buildConnectionTestStats, buildHealthCheckStats, buildHealthStats, } from "./connections-format.js";
+import { withOverflowFooter, truncatedByLimitNote } from "./list-footer.js";
+import { CONNECTION_TABLE_COLUMNS, CONNECTION_FULL_COLUMNS, CONNECTION_COMPACT_COLUMNS, CONNECTION_LIST_NEXT_STEPS, RESOURCE_TABLE_COLUMNS, mapConnectionRow, mapConnectionRowFull, compactConnectionRow, mapResourceRow, buildConnectionDetail, buildConnectionTestStats, buildHealthCheckStats, buildHealthStats, } from "./connections-format.js";
 // W3 Stage-2 hardening — applyTrim + extractResourceList live in the
 // sibling connections-trim.ts (pure functions, ~200 lines). Imported for
 // internal use by the connection_data + connection_resources handlers,
@@ -25,6 +26,7 @@ export { applyTrim, extractResourceList };
 // formatter; connection_get / _update / _delete pass through unwrapEntity
 // + the rich-card builder which already reads from the same row map.
 import { normalizeConnectionFromWire } from "./normalizers.js";
+import { normalizeResourceIdFields } from "./resource-id.js";
 /**
  * F-15 (W1.9) — downstream probe of api.wootsup.com from `apimapper_health`.
  *
@@ -72,13 +74,16 @@ async function probeApimapperApi() {
 /**
  * Register the connection CRUD + probe + sample + pipeline 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, `connection_create` falls back to a structured
- *   error on genuine credential ambiguity instead of prompting.
+ * Chat-first disambiguation (decision 2026-06-15): on genuine credential
+ * ambiguity `connection_create` 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
+ * (`apimapper_oauth_authorize_begin` in credentials.ts), so this module no
+ * longer takes an elicitation capability.
+ *
+ * @param server the tool registrar (essentials forward, rest captured).
  */
-export function registerConnectionTools(server, elicitation) {
+export function registerConnectionTools(server) {
     // ── apimapper_health ───────────────────────────────────────────────
     server.registerTool("apimapper_health", {
         title: "API Mapper REST Health",
@@ -159,17 +164,28 @@ export function registerConnectionTools(server, elicitation) {
         // rc.10 A5 (2026-05-19) — description states the default limit
         // already covers a typical install. The Maria-walkthrough log
         // showed AI defaulting to limit:200/500 reflexively.
-        description: "List all API Mapper connections. The default limit of 50 already covers a typical install — " +
-            "most customers run with 5-25 connections, increase the limit only if you have a specific " +
-            "reason to expect more. Use apimapper_connection_get for full details of a single connection." +
-            "\n\nExample:\n  apimapper_connection_list({})  // returns up to 50 connections in one call\n" +
-            "  apimapper_connection_list({ source: 'user' })  // narrow to user-created only",
+        description: "List API Mapper connections — a LEAN projection by default (id / name / source / host / health). " +
+            "The default limit of 25 already covers a typical install — most customers run with 5-25 " +
+            "connections, increase the limit only if you have a specific reason to expect more. " +
+            "Pass `fields: ['all']` for the full dump (endpoint URL, method, auth_type, credential_id), " +
+            "or a list of specific extra columns. Use apimapper_connection_get for full details of a single connection." +
+            "\n\nExample:\n  apimapper_connection_list({})  // lean projection, up to 25 connections\n" +
+            "  apimapper_connection_list({ source: 'user' })  // narrow to user-created only\n" +
+            "  apimapper_connection_list({ fields: ['all'] })  // full detail dump",
         inputSchema: {
             source: z
                 .enum(["library", "demo", "user", "all"])
                 .default("all")
                 .describe("Filter by origin"),
-            limit: z.number().min(1).max(500).default(50).describe("Max items (1-500). Default 50 already covers a typical install — do not raise unless you have evidence the list is larger."),
+            limit: z.number().min(1).max(500).default(25).describe("Max items (1-500). Default 25 already covers a typical install — do not raise unless you have evidence the list is larger."),
+            // F198 — opt-in full detail. The default projection is the lean
+            // id/name/source/host/health set; `fields` widens it. `['all']` (or
+            // any non-empty array) returns the full endpoint/method/auth/cred dump.
+            fields: z
+                .array(z.string().min(1))
+                .optional()
+                .describe("Opt into extra columns. Omit for the lean default (id/name/source/host/health). " +
+                "Pass ['all'] for the full dump (endpoint URL, method, auth_type, credential_id)."),
             // W1.18 (F-32) — case-insensitive substring filter applied
             // in-memory AFTER the upstream fetch (no per-name REST call).
             // Min 2 chars at the schema boundary blocks the single-char
@@ -181,7 +197,7 @@ export function registerConnectionTools(server, elicitation) {
                 .describe("Case-insensitive substring filter on connection name. Applied in-memory after the upstream fetch — does NOT change the REST query. Must be 2+ characters; single-char probes are blocked. Combine with `source` for narrower results."),
         },
         annotations: readOnly({ title: "List Connections", openWorld: true }),
-    }, async ({ source, limit, name_query }) => {
+    }, async ({ source, limit, name_query, fields }) => {
         const r = await request("/connections");
         if (!r.success) {
             return restErrorResult(r, { source, limit, name_query }, { message: "connection list failed" });
@@ -199,18 +215,41 @@ export function registerConnectionTools(server, elicitation) {
         // subset, not the haystack. See `filterByNameQuery` JSDoc for the
         // case-folding + undefined-skip contract shared with flow_list.
         items = filterByNameQuery(items, name_query);
+        // F198 — capture the matched total BEFORE the slice so the footer can
+        // report exactly how many rows were dropped by the limit.
+        const totalMatched = items.length;
         items = items.slice(0, limit);
+        // F198 — opt into the full detail dump only when `fields` is supplied.
+        // Any non-empty `fields` array (typically ['all']) widens the table to
+        // the full column set; the default stays the lean projection.
+        const wantFull = Array.isArray(fields) && fields.length > 0;
+        // F198 — the honest "N more — filter with name_query or raise limit"
+        // note fires whenever the limit actually dropped matched rows. The
+        // compact-render note (withOverflowFooter) still rides along for the
+        // truncated-text case.
+        const overflowNote = truncatedByLimitNote(totalMatched, limit, "connections");
+        const baseFooter = overflowNote
+            ? `${CONNECTION_LIST_NEXT_STEPS}\n${overflowNote}`
+            : CONNECTION_LIST_NEXT_STEPS;
         // W3.1 — tableResult: ASCII table for the LLM + typed DataTable payload
-        // for the Rich Card. T1 (W3.2): explicit compactColumns/compactMap drop
-        // ENDPOINT/METHOD/CRED at 21+ rows. IA-7: id stays llmOnly. IA-10: the
-        // footer carries the next-step guidance.
+        // for the Rich Card. Default = lean projection (id/name/source/host/
+        // health); `fields` = full dump. IA-7: id stays llmOnly. IA-10: the
+        // footer carries the next-step guidance + the F198 overflow note.
         return tableResult(toRows(items), {
-            columns: CONNECTION_TABLE_COLUMNS,
+            columns: wantFull ? CONNECTION_FULL_COLUMNS : CONNECTION_TABLE_COLUMNS,
             compactColumns: CONNECTION_COMPACT_COLUMNS,
-            map: mapConnectionRow,
+            map: wantFull ? mapConnectionRowFull : mapConnectionRow,
             compactMap: compactConnectionRow,
-            header: (n) => `${n} connections`,
-            footer: CONNECTION_LIST_NEXT_STEPS,
+            // F198 — the "N more" overflow note rides in the HEADER (rendered
+            // first, never truncated) so it survives even when a 21+ row table
+            // compacts to 2000 chars and drops the footer. The footer keeps the
+            // next-step guidance + the compact-render note for the non-overflow
+            // truncation case.
+            header: (n) => (overflowNote ? `${n} connections — ${overflowNote}` : `${n} connections`),
+            // Minor (2026-06-10): at 21+ rows the toolkit compacts the LLM-visible
+            // table to 2000 chars — append an honest "use filters" note so the
+            // agent does not mistake a truncated list for the full set.
+            footer: withOverflowFooter(baseFooter, items.length, "connections"),
         });
     });
     // ── apimapper_connection_get ───────────────────────────────────────
@@ -255,26 +294,44 @@ export function registerConnectionTools(server, elicitation) {
         // W3.1 — detailResult: grouped key-value detail for the Rich Card.
         // IA-7: opaque IDs are copyable code entries. IA-10: a dedicated
         // "Next steps" group carries the follow-up calls.
-        return buildConnectionDetail(id, conn);
+        // F9 (2026-06-09): run the same camelCase→snake_case wire bridge the
+        // list path applies (F-LS-04) — buildConnectionDetail reads
+        // c.auth_type/credential_id; the raw wire shape carries authType/
+        // credentialId, so without this the detail rendered auth "none"
+        // while the list showed the real auth for the SAME connection.
+        return buildConnectionDetail(id, normalizeConnectionFromWire(conn));
     });
     // ── apimapper_connection_create ────────────────────────────────────
     server.registerTool("apimapper_connection_create", {
         title: "Create Connection",
         description: "Create a custom connection. **Use ONLY when no library template matches your target API.** " +
-            "First call `apimapper_library_featured()` or `apimapper_library_list({ query: '<api-name>' })` — " +
+            "First call `apimapper_library_featured()` or `apimapper_library_list({ search: '<api-name>' })` (min 3 chars) — " +
             "Google Sheets, Calendly, Notion, Airtable, GitHub, Pexels, Unsplash, OpenWeatherMap, REST Countries, " +
             "Google Drive/Docs/Slides/Tasks all have ready-to-use templates with auto-configured auth and " +
             "field-detection. Library activation via `apimapper_library_activate({ id })` is the canonical " +
             "customer path; connection_create is the fallback for niche or unknown APIs. " +
             "The server enforces this: a custom create on an API already covered by a curated template is " +
             "blocked with a 409 naming the template to activate — pass `acknowledge_no_library: true` to " +
-            "intentionally override that block." +
+            "intentionally override that block. " +
+            // A16 (2026-06-10): the guard matches on the HOST, so a genuinely
+            // uncovered endpoint never blocks — do NOT set acknowledge_no_library
+            // pre-emptively.
+            "The guard matches on the request HOST against the curated library; a connection to an " +
+            "uncovered host is NEVER blocked and needs no `acknowledge_no_library` — only set that flag " +
+            "AFTER you actually receive a 409." +
+            "\n\nNote: connection auth_type spellings differ from apimapper_credential_create's: " +
+            "here it is `basic` / `oauth2`, whereas credential_create uses `basic_auth` / `oauth2_code` / `oauth2_cc`. " +
+            "Use the spelling for the tool you are calling." +
             "\n\nExample:\n  apimapper_connection_create({ name: 'Pexels API', endpoint: 'https://api.pexels.com/v1/search', method: 'GET', auth_type: 'bearer', items_path: 'photos' })",
         inputSchema: {
             name: z.string().min(1).describe('Connection name (e.g., "My Blog API")'),
             endpoint: z.string().describe('Endpoint path or full URL (e.g., "https://api.example.com/posts")'),
             method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET").describe("HTTP method"),
-            auth_type: z.enum(["none", "api_key", "bearer", "basic", "oauth2"]).default("none").describe("Auth type (snake_case wire key)"),
+            auth_type: z
+                .enum(["none", "api_key", "bearer", "basic", "oauth2"])
+                .default("none")
+                .describe("Auth type (snake_case wire key). " +
+                "NB: credential_create spells these `basic_auth` (here `basic`) and `oauth2_code`/`oauth2_cc` (here `oauth2`)."),
             credential_id: z.string().optional().describe("Credential ID (snake_case wire key) if auth_type requires one"),
             items_path: z.string().optional().describe('JSONPath to items array (snake_case wire key)'),
             cache_ttl: z.number().int().min(0).default(3600).describe("Cache TTL in seconds (snake_case wire key)"),
@@ -288,9 +345,19 @@ export function registerConnectionTools(server, elicitation) {
             acknowledge_no_library: z.boolean().optional().describe("Set true ONLY when no library template fits and you intentionally need a custom connection. " +
                 "The server blocks custom creates on APIs that already have a curated library template; " +
                 "this flag is the audited override. Prefer apimapper_library_activate({ id }) when a template exists."),
+            // Phase 2.7 (change protocol): the action is IMPLICIT
+            // (`connection.created`) — only `summary` is needed; the handler
+            // defaults the action. Threaded into the POST body as
+            // `change: { summary }` (conditional, never a top-level key).
+            summary: z
+                .string()
+                .max(280)
+                .optional()
+                .describe('Optional one-line summary of this change for the change history ' +
+                '(e.g., "Added a Pexels photo connection").'),
         },
         annotations: creating({ title: "Create Connection", openWorld: true }),
-    }, async (input) => {
+    }, async ({ summary, ...input }) => {
         // W3.6 — when the connection's auth_type needs a credential and none is
         // given: exactly 1 stored credential → auto-pick; >1 → elicitChoice;
         // elicitChoice null (unsupported client / declined) → structured
@@ -314,31 +381,39 @@ export function registerConnectionTools(server, elicitation) {
                 resolvedInput = { ...input, credential_id: creds[0].id };
             }
             else {
+                // Chat-first disambiguation (decision 2026-06-15): the native
+                // elicitation picker renders as a clunky collapsed TUI in some
+                // hosts. For an ordinary credential pick the assistant asking in
+                // plain chat is nicer, so we skip the picker and return the
+                // structured candidate-list error directly — its `candidates`
+                // carry id+label, so the assistant sees the names and can ask.
+                // (The OAuth authorize path KEEPS the picker: explicit consent on
+                // WHICH credential to authorize is security-relevant.)
                 const candidates = creds.map((c) => ({
                     id: c.id,
                     label: c.name,
                 }));
-                const picked = elicitation
-                    ? await elicitChoice(elicitation, `The "${input.name}" connection (auth_type: ${input.auth_type}) needs a ` +
-                        "credential. Pick which stored credential to use.", candidates.map((c) => c.id))
-                    : null;
-                if (picked === null) {
-                    return ambiguityFallbackError({
-                        code: "credential_ambiguous",
-                        paramName: "credential_id",
-                        what: "credentials",
-                        candidates,
-                        extraDetails: { name: input.name, auth_type: input.auth_type },
-                    });
-                }
-                resolvedInput = { ...input, credential_id: picked };
+                return ambiguityFallbackError({
+                    code: "credential_ambiguous",
+                    paramName: "credential_id",
+                    what: "credentials",
+                    candidates,
+                    extraDetails: { name: input.name, auth_type: input.auth_type },
+                });
             }
         }
+        // Phase 2.7 — implicit action (`connection.created`); attach `change:
+        // { summary }` only when supplied so the body is unchanged otherwise.
+        // `summary` was destructured out of `input` above, so it never leaks as a
+        // top-level connection column.
+        const createBody = summary !== undefined
+            ? { ...resolvedInput, change: { summary } }
+            : resolvedInput;
         // PHP fromControllerResponse(_, 'connection', 201) → {success, connection:{…}}.
         // Audit: F-A1-02.
         const r = await request("/connections", {
             method: "POST",
-            body: JSON.stringify(resolvedInput),
+            body: JSON.stringify(createBody),
         });
         if (!r.success) {
             // M1 (MCP-relay audit) — wire-shape parity with the admin-ui. On the
@@ -388,7 +463,7 @@ export function registerConnectionTools(server, elicitation) {
             name: conn?.name,
             source: conn?.source,
             next_steps: [
-                "Use apimapper_connection_test to verify reachability, then apimapper_flow_create to wire it into a flow.",
+                'Verify reachability via apimapper_advanced({ tool: "apimapper_connection_test", arguments: { id } }), then build a flow with apimapper_flow_setup_with_sources (or apimapper_advanced({ tool: "apimapper_flow_create" })).',
             ],
         }, false, { maxChars: 2000 });
     });
@@ -411,14 +486,28 @@ export function registerConnectionTools(server, elicitation) {
                 // .strict() allow-list here risks rejecting a legit field the
                 // server accepts, so the schema stays permissive.
                 'Unknown keys are dropped by the server (column-whitelisted on write).'),
+            // Phase 2.7 (change protocol): the action is IMPLICIT
+            // (`connection.updated`) — only `summary` is needed; the handler
+            // defaults the action. Threaded into the PUT body as
+            // `change: { summary }` (sibling of the patch fields).
+            summary: z
+                .string()
+                .max(280)
+                .optional()
+                .describe('Optional one-line summary of this change (e.g., "Pointed the endpoint at /v2/posts").'),
         },
         annotations: mutating({ title: "Update Connection", openWorld: true }),
-    }, async ({ id, patch }) => {
+    }, async ({ id, patch, summary }) => {
+        // Phase 2.7 — implicit action (`connection.updated`); attach `change:
+        // { summary }` only when supplied so the body is unchanged otherwise.
+        const updateBody = summary !== undefined
+            ? { ...patch, change: { summary } }
+            : patch;
         // PHP fromControllerResponse(_, 'connection') → {success, connection:{…}}.
         // Audit: F-A1-03.
         const r = await request(`/connections/${encodeURIComponent(id)}`, {
             method: "PUT",
-            body: JSON.stringify(patch),
+            body: JSON.stringify(updateBody),
         });
         if (!r.success) {
             return restErrorResult(r, { id }, { message: "connection update failed" });
@@ -432,7 +521,7 @@ export function registerConnectionTools(server, elicitation) {
             id: conn?.id,
             name: conn?.name,
             next_steps: [
-                "Re-run apimapper_connection_test if endpoint/auth changed; flows referencing this connection may need to be republished.",
+                'Re-test if endpoint/auth changed via apimapper_advanced({ tool: "apimapper_connection_test", arguments: { id } }); flows referencing this connection may need to be republished via apimapper_flow_full_recompile_publish.',
             ],
         }, false, { maxChars: 2000 });
     });
@@ -535,7 +624,7 @@ export function registerConnectionTools(server, elicitation) {
             name: conn?.name,
             applied_patch_keys: Object.keys(patch),
             next_steps: [
-                "Verify with apimapper_connection_get; re-run apimapper_connection_test before re-publishing flows.",
+                'Verify via apimapper_advanced({ tool: "apimapper_connection_get", arguments: { id } }); re-test via apimapper_advanced({ tool: "apimapper_connection_test", arguments: { id } }) before re-publishing flows.',
             ],
         }, false, { maxChars: 2000 });
     });
@@ -551,14 +640,29 @@ export function registerConnectionTools(server, elicitation) {
                 .boolean()
                 .default(false)
                 .describe("Must be true to execute. On confirm:false, returns a preview."),
+            // Phase 2.7 (change protocol): the action is IMPLICIT
+            // (`connection.deleted`) — only `summary` is needed; the handler
+            // defaults the action. Attached to the DELETE body as
+            // `change: { summary }` (the delete otherwise has no body), and only on
+            // the real delete — the preview branch never records a change.
+            summary: z
+                .string()
+                .max(280)
+                .optional()
+                .describe('Optional one-line summary of this deletion (e.g., "Removed the unused Pexels connection").'),
         },
         annotations: destructive({ title: "Delete Connection", openWorld: true }),
-    }, async ({ id, confirm }) => {
+    }, async ({ id, confirm, summary }) => {
         if (!confirm) {
             // PHP fromControllerResponse(_, 'connection') wraps as
             // {success, connection:{…}}. Unwrap defensively. Audit: F-A1-04.
             const preview = await request(`/connections/${encodeURIComponent(id)}`);
-            const conn = preview.success ? unwrapEntity(preview.data, "connection") : undefined;
+            const rawConn = preview.success ? unwrapEntity(preview.data, "connection") : undefined;
+            // F9 (2026-06-09): same wire-shape bridge as connection_get — the
+            // preview target read auth_type off the raw camelCase wire shape.
+            const conn = rawConn
+                ? normalizeConnectionFromWire(rawConn)
+                : undefined;
             return formatResult({
                 preview: true,
                 warning: "DESTRUCTIVE — Connection delete cannot be undone. Dependent flows will break.",
@@ -574,7 +678,15 @@ export function registerConnectionTools(server, elicitation) {
                 instruction: "Ask user to confirm, then call again with confirm: true.",
             });
         }
-        const r = await request(`/connections/${encodeURIComponent(id)}`, { method: "DELETE" });
+        // Phase 2.7 — implicit action (`connection.deleted`); attach `change:
+        // { summary }` only when supplied so the request is unchanged otherwise.
+        const r = await request(`/connections/${encodeURIComponent(id)}`, summary !== undefined
+            ? {
+                method: "DELETE",
+                body: JSON.stringify({ change: { summary } }),
+                headers: { "Content-Type": "application/json" },
+            }
+            : { method: "DELETE" });
         if (!r.success) {
             return restErrorResult(r, { id }, { message: "connection delete failed" });
         }
@@ -672,6 +784,11 @@ export function registerConnectionTools(server, elicitation) {
             "the response items in-memory — this does NOT trigger multi-page fetch upstream (the " +
             "request is single-shot). Use `fields` to project each item down to a whitelist of leaf " +
             "keys, cutting response size on sparse queries." +
+            "\n\nF144: if a library/template connection returns a 'Please configure …' / 'Please select an " +
+            "endpoint' diagnostic, the missing values are TEMPLATE FIELDS — supply them here via " +
+            "`template_fields` (e.g., { spreadsheet_id: '…' }) rather than re-creating the connection or " +
+            "starting a new OAuth flow. A connection whose template_fields are already resolved IS " +
+            "configured; inspect them with apimapper_connection_get({ id })." +
             "\n\nExample:\n" +
             "  apimapper_connection_data({ id: 'con_abc123', limit: 10 })  // first 10 items\n" +
             "  apimapper_connection_data({ id: 'con_abc123', limit: 5, offset: 10 })  // skip 10, take 5\n" +
@@ -684,7 +801,11 @@ export function registerConnectionTools(server, elicitation) {
                 .trim()
                 .min(1)
                 .optional()
-                .describe('Override endpoint (e.g., "Scheduled Events"). Empty-string and whitespace-only values are rejected at the schema boundary to prevent "?endpoint=" query garbage; omit the field entirely to use the connection default.'),
+                .describe('Named endpoint SELECTION — NOT a URL. This is the label of a configured endpoint on the ' +
+                'connection (e.g., "Scheduled Events", "Get Values"), the same names connection_create exposes ' +
+                'as endpoints[]. List them via apimapper_connection_get({ id }). Empty-string and ' +
+                'whitespace-only values are rejected at the schema boundary to prevent "?endpoint=" query ' +
+                "garbage; omit the field entirely to use the connection default."),
             template_fields: z
                 .record(z.string(), z.union([z.string(), z.number().finite(), z.boolean()]))
                 .optional()
@@ -726,7 +847,11 @@ export function registerConnectionTools(server, elicitation) {
         // implicitly, but the explicit guard documents the contract and keeps
         // TypeScript happy under the wider schema.
         if (template_fields) {
-            for (const [k, v] of Object.entries(template_fields)) {
+            // A5 (2026-06-10): normalize a pasted Drive/Sheets URL in
+            // template_fields.spreadsheet_id to the bare ID before it becomes a
+            // query param — the {{spreadsheet_id}} placeholder needs the bare id.
+            const normalizedFields = normalizeResourceIdFields(template_fields);
+            for (const [k, v] of Object.entries(normalizedFields)) {
                 params.set(k, typeof v === "string" ? v : String(v));
             }
         }
@@ -789,6 +914,25 @@ export function registerConnectionTools(server, elicitation) {
                 ? pickFields(item, fields)
                 : item);
         }
+        // F198 (Desktop-E2E #2 forensics, 2026-06-12): a 0-row read used to ship
+        // the full {ok, shape, item_count, payload:[], body, content_type}
+        // envelope — pure overhead when there is nothing to show. Collapse it to
+        // a compact 1-liner that names the likely culprits (template_fields /
+        // range) and forwards the upstream diagnostic verbatim when present.
+        // Only the array-empty case collapses; an empty object/scalar payload is
+        // a different (rare) shape and keeps the full envelope.
+        if (Array.isArray(trim.payload) && trim.itemCount === 0) {
+            const diagnosticMsg = diagnostic && typeof diagnostic.message === "string"
+                ? ` ${diagnostic.message}`
+                : "";
+            return formatResult({
+                ok: true,
+                item_count: 0,
+                note: "0 rows — check template_fields (e.g. spreadsheet_id / range) or the connection " +
+                    "endpoint; sample the config with apimapper_connection_get({ id })." +
+                    diagnosticMsg,
+            }, false, { maxChars: 600 });
+        }
         return formatResult({
             ok: true,
             // F-38 — surface a stable, narrow shape enum instead of typeof.
@@ -817,12 +961,14 @@ export function registerConnectionTools(server, elicitation) {
         title: "List Connection Resources",
         description: "List browseable resources on a connection (drive files, sheets, IG media). " +
             "REST contract: `field` (resource-picker field name) + optional `query` filter." +
-            "\n\nExample:\n  apimapper_connection_resources({ id: 'con_drive_xyz', field: 'fileId', query: 'budget' })",
+            // 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_connection_resources\", arguments: { id: \"con_drive_xyz\", field: \"fileId\", query: \"budget\" } })",
         inputSchema: {
             id: z.string().describe("Connection ID. Use apimapper_connection_list to find."),
             field: z
                 .string()
-                .describe('Resource-picker field name (e.g., "spreadsheet_id", "drive_file_id"). REST wire-key: field.'),
+                .describe('REQUIRED — resource-picker field name (e.g., "spreadsheet_id", "drive_file_id"). REST wire-key: field.'),
             // rc.10 A4 (2026-05-19): min(3) blocks the single-char "p", "j", "u"
             // probing pattern observed in Maria-walkthrough logs.
             // rc.13 W1.17 (F-29): Master-Doc-Drift — Master requested min(2), kept
@@ -868,21 +1014,29 @@ export function registerConnectionTools(server, elicitation) {
     server.registerTool("apimapper_connection_pipeline_update", {
         title: "Update Connection Pipeline",
         description: "Update the connection's pipeline (endpoints, default_params, default_headers, headers, items_path, items_shape, body, body_type, graphql_variables, response_type)." +
+            "\n\nWorks on connections WITHOUT a stored pipeline: the protocol keys version/enabled/steps are NOT required — send only the connection-column keys you care about (F184)." +
+            "\n\nPARTIAL UPDATES ARE SAFE (F145) — send only the keys you want to change:" +
+            "\n  • Object-map keys (default_params, default_headers, headers, graphql_variables) MERGE into the stored map: changing one entry preserves the others. Pass a value of null to delete a single stored entry (e.g. { default_params: { stale_key: null } })." +
+            "\n  • Scalar keys (items_path, items_shape, body, body_type, response_type) replace their single value." +
+            "\n  • List keys (endpoints) are REPLACED wholesale (positional merge is ambiguous) — resend every endpoint you want to keep. If a replace drops endpoints, the response carries a `warnings` array naming what was removed." +
             "\n\nitems_shape values: 'flat' (default, list of objects), 'auto' (best-effort detection), 'headers_rows' (pivot 2D array [[h1,h2],[v1,v2],...] into named-object rows — use this for Google-Sheets-style responses), 'object_keys' (turn a keyed object into a list)." +
-            "\n\nExample:\n  apimapper_connection_pipeline_update({ id: 'con_abc123', pipeline: { items_path: 'photos', items_shape: 'auto', default_params: { per_page: '20' } } })" +
+            "\n\nExample (partial — preserves any other stored params):\n  apimapper_connection_pipeline_update({ id: 'con_abc123', pipeline: { items_path: 'photos', items_shape: 'auto', default_params: { per_page: '20' } } })" +
             "\n\nGoogle-Sheets 2D array example:\n  apimapper_connection_pipeline_update({ id: 'con_sheet', pipeline: { items_shape: 'headers_rows' } })",
         inputSchema: {
             id: z.string().describe("Connection ID. Use apimapper_connection_list to find."),
             pipeline: z
                 .record(z.string(), z.unknown())
-                .describe('Pipeline JSON. Accepts connection-column keys: endpoints, default_params, default_headers, headers, items_path, items_shape, body, body_type, graphql_variables, response_type. ' +
+                .describe('Pipeline JSON (partial allowed). Accepts connection-column keys: endpoints, default_params, default_headers, headers, items_path, items_shape, body, body_type, graphql_variables, response_type. ' +
+                'Object-map keys (default_params/default_headers/headers/graphql_variables) MERGE into stored values (null deletes one entry); scalar keys replace; list keys (endpoints) replace wholesale and report dropped entries in a warnings array. ' +
                 'items_shape options: "flat" | "auto" | "headers_rows" | "object_keys". ' +
                 'Example: {"items_path":"data","items_shape":"headers_rows"}.'),
         },
         annotations: mutating({ title: "Update Connection Pipeline", openWorld: true }),
     }, async ({ id, pipeline }) => {
         // PHP ConnectionPipelineHandler uses fromControllerResponse(_, 'connection')
-        // → {success, connection:{…}}. Unwrap defensively. Audit: F-A1-07.
+        // → {success, connection:{…}}. F145: a list-key (endpoints) full-replace
+        // also carries a top-level `warnings` array naming dropped entries.
+        // Unwrap defensively. Audit: F-A1-07.
         const r = await request(`/connections/${encodeURIComponent(id)}/pipeline`, {
             method: "PUT",
             body: JSON.stringify(pipeline),
@@ -891,7 +1045,20 @@ export function registerConnectionTools(server, elicitation) {
             return restErrorResult(r, { id }, { message: "connection pipeline update failed" });
         }
         const conn = unwrapEntity(r.data, "connection");
-        return formatResult({ updated: true, id: conn?.id, name: conn?.name }, false, { maxChars: 2000 });
+        // Surface F145 dropped-entry warnings so the agent never silently loses
+        // endpoints on a partial replace.
+        const warnings = r.data && typeof r.data === "object" && Array.isArray(r.data.warnings)
+            ? r.data.warnings
+            : undefined;
+        const payload = {
+            updated: true,
+            id: conn?.id,
+            name: conn?.name,
+        };
+        if (warnings && warnings.length > 0) {
+            payload.warnings = warnings;
+        }
+        return formatResult(payload, false, { maxChars: 2000 });
     });
 }
 //# sourceMappingURL=connections.js.map