@wootsup/mcp 0.1.0-rc.8 → 0.1.0

package/dist/modules/apimapper/connections.js

@@ -1,23 +1,127 @@
 import { z } from "zod";
-import { formatResult, autoFormatTable, readOnly, creating, mutating, destructive, errorWithSuggestion, } from "@getimo/mcp-toolkit";
+import { formatResult, tableResult, errorResult, readOnly, creating, mutating, destructive, errorWithSuggestion, pickFields, createProgressReporter, elicitChoice, } from "@getimo/mcp-toolkit";
 import { request, hintFor, WP_BASE, WP_USER, authConfigured } from "./client.js";
+import { toRows } from "./types.js";
 import { unwrapEntity } from "./envelope.js";
-export function registerConnectionTools(server) {
+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";
+// 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,
+// and re-exported so the public surface
+// `import { ... } from "./connections.js"` stays unchanged for existing
+// callers and the test suite.
+import { applyTrim, extractResourceList, } from "./connections-trim.js";
+export { applyTrim, extractResourceList };
+// F-LS-04 (live-smoke 2026-05-20) — the PHP /connections endpoint emits
+// camelCase keys (authType, credentialId, ...). Every formatter + consumer
+// in this module reads snake_case. The wire-shape normaliser bridges
+// the two so the AI no longer sees auth=none / credential=— on real
+// upstream connections. Applied at the connection_list handler — that is
+// the only tool that fans out raw connection items to a downstream
+// 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";
+/**
+ * F-15 (W1.9) — downstream probe of api.wootsup.com from `apimapper_health`.
+ *
+ * The customer's WP-REST probe alone cannot distinguish "your server is fine
+ * but getimo's license/release infra is degraded" from a generic failure.
+ * Hitting the upstream `/health` endpoint surfaces that signal so an AI
+ * client can route the user to the right troubleshooting branch.
+ */
+const APIMAPPER_API_HEALTH_URL = "https://api.wootsup.com/health";
+/**
+ * 3-second budget — health is meant to be a fast snapshot. Shorter than
+ * diagnose's 5s because diagnose probes a customer-controlled server (which
+ * may legitimately be slow under load), while api.wootsup.com is
+ * getimo-controlled CDN-backed infra that should respond in <500ms.
+ */
+const APIMAPPER_API_HEALTH_TIMEOUT_MS = 3_000;
+/**
+ * F-15: probe api.wootsup.com/health and map the outcome to a stable
+ * status-string. NEVER throws — the health tool's contract is to surface
+ * downstream failure as data, not to fail itself when the downstream is
+ * unreachable. The four return values form a closed enum:
+ *
+ *   - "OK"           — 2xx response from api.wootsup.com
+ *   - "HTTP N"       — non-2xx response (e.g. "HTTP 503")
+ *   - "timeout"      — AbortError/TimeoutError after 3s
+ *   - "unreachable"  — any other fetch error (DNS, refused, TLS, etc.)
+ *
+ * Reuses fetchWithTimeout from diagnose.ts so the AbortSignal.timeout
+ * wiring lives in exactly one place (DRY across probe call sites).
+ */
+async function probeApimapperApi() {
+    try {
+        const res = await fetchWithTimeout(APIMAPPER_API_HEALTH_URL, { method: "GET" }, APIMAPPER_API_HEALTH_TIMEOUT_MS);
+        if (res.ok)
+            return "OK";
+        return `HTTP ${res.status}`;
+    }
+    catch (e) {
+        if (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError")) {
+            return "timeout";
+        }
+        return "unreachable";
+    }
+}
+/**
+ * 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.
+ */
+export function registerConnectionTools(server, elicitation) {
     // ── apimapper_health ───────────────────────────────────────────────
     server.registerTool("apimapper_health", {
         title: "API Mapper REST Health",
         description: "Check connectivity + auth against the API Mapper REST namespace. " +
-            "Returns {wp_base, wp_user, auth, connectivity, connection_count, http_status}. " +
+            "Returns {wp_base, wp_user, auth, connectivity, connection_count, http_status, apimapper_api_status}. " +
+            "`apimapper_api_status` reports the downstream api.wootsup.com health (OK/HTTP N/timeout/unreachable) " +
+            "so a degradation of getimo infra is distinguishable from a customer-server issue. " +
             "Run this first if any other tool fails." +
             "\n\nExample:\n  apimapper_health({})",
         inputSchema: {},
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Health Check", openWorld: true }),
     }, async () => {
         const checks = {
             wp_base: WP_BASE,
             wp_user: WP_USER,
             auth: authConfigured() ? "configured" : "MISSING (set APIMAPPER_WP_APP_PASS)",
         };
+        // L-5 (W3F-5): when the customer uses bearer-only auth (the modern
+        // `amk_live_…` flow), APIMAPPER_WP_USER is intentionally unset, so
+        // the previous render emitted `WP user: ""`. Probe `/identity` and
+        // fall back to its `.username` field — it's anon-readable on both
+        // platforms and never throws. The probe is cheap (single GET) and
+        // runs alongside the existing api.wootsup.com probe.
+        if (checks.wp_user === "") {
+            try {
+                const idRes = await request("/identity");
+                const fromIdentity = idRes.success && typeof idRes.data?.username === "string"
+                    ? idRes.data.username
+                    : "";
+                if (fromIdentity !== "") {
+                    checks.wp_user = fromIdentity;
+                }
+            }
+            catch {
+                // Identity probe failure is non-fatal — the rest of the
+                // health snapshot still surfaces.
+            }
+        }
+        // F-15 (W1.9) — downstream api.wootsup.com probe. Runs before the
+        // WP-REST check; both are independent, but sequential is cheap (3s
+        // worst-case for the api probe, then the WP probe) and keeps the
+        // result ordering deterministic. Probe never throws — surfaces as
+        // status string per probeApimapperApi contract.
+        checks.apimapper_api_status = await probeApimapperApi();
         try {
             const r = await request("/connections");
             checks.http_status = r.status ?? 0;
@@ -35,60 +139,74 @@ export function registerConnectionTools(server) {
             const err = errorWithSuggestion(e, { healthTool: "apimapper_health" });
             checks.connectivity = `ERROR: ${err.message}`;
         }
-        return formatResult(checks, false, { maxChars: 2000 });
+        // W3.1 — health snapshot is a flat scalar set: statsResult is the
+        // goldstandard fit. Every check becomes a stat so an AI client reads
+        // connectivity/auth/downstream state without parsing free text.
+        return buildHealthStats(checks);
     });
     // ── apimapper_connection_list ──────────────────────────────────────
     server.registerTool("apimapper_connection_list", {
         title: "List Connections",
-        description: "List all API Mapper connections. Use apimapper_connection_get for full details." +
-            "\n\nExample:\n  apimapper_connection_list({ source: 'user', limit: 25 })",
+        // 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",
         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)"),
+            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."),
+            // 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
+            // probe-thrash pattern observed in the Maria-walkthrough logs.
+            name_query: z
+                .string()
+                .min(2)
+                .optional()
+                .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(),
-    }, async ({ source, limit }) => {
+        annotations: readOnly({ title: "List Connections", openWorld: true }),
+    }, async ({ source, limit, name_query }) => {
         const r = await request("/connections");
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { source, limit },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return errorResult({
+                message: r.error ?? "connection list failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { source, limit, name_query },
+            });
         }
-        let items = Array.isArray(r.data?.connections) ? r.data.connections : [];
+        // F-LS-04 — normalise the camelCase wire shape (authType, credentialId,
+        // …) to snake_case BEFORE anything downstream reads it. The
+        // `Connection` domain type uses snake_case keys, so the result is
+        // safely cast back: `normalizeConnectionFromWire` only adds keys, it
+        // never drops them, and existing snake_case values win on collision.
+        const rawItems = Array.isArray(r.data?.connections) ? r.data.connections : [];
+        let items = rawItems.map((c) => normalizeConnectionFromWire(c));
         if (source !== "all")
             items = items.filter((c) => c.source === source);
+        // W1.18 (F-32) — filter BEFORE slice so limit applies to the matched
+        // subset, not the haystack. See `filterByNameQuery` JSDoc for the
+        // case-folding + undefined-skip contract shared with flow_list.
+        items = filterByNameQuery(items, name_query);
         items = items.slice(0, limit);
-        return autoFormatTable(items.map((c) => ({
-            id: c.id,
-            name: c.name,
-            source: c.source,
-            endpoint: c.endpoint || "(template)",
-            method: c.method || "GET",
-            auth_type: c.auth_type || "none",
-            credential_id: c.credential_id || "—",
-        })), {
-            columns: [
-                // Width 36 accommodates 30+ char IDs (e.g. legacy template
-                // connections like conn_calendly_jla_229fcbce95b7). Truncation
-                // produces orphan IDs that downstream tools fail to resolve
-                // via *_get; +6 headroom matches the longest historical IDs.
-                { key: "id", label: "ID", width: 36 },
-                { key: "name", label: "NAME", width: 28 },
-                { key: "source", label: "SRC", width: 8 },
-                { key: "endpoint", label: "ENDPOINT", width: 30 },
-                { key: "method", label: "M", width: 5 },
-                { key: "auth_type", label: "AUTH", width: 12 },
-                { key: "credential_id", label: "CRED", width: 26 },
-            ],
+        // 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.
+        return tableResult(toRows(items), {
+            columns: CONNECTION_TABLE_COLUMNS,
+            compactColumns: CONNECTION_COMPACT_COLUMNS,
+            map: mapConnectionRow,
+            compactMap: compactConnectionRow,
             header: (n) => `${n} connections`,
-            footer: "Use apimapper_connection_get <id> for full details.",
+            footer: CONNECTION_LIST_NEXT_STEPS,
         });
     });
     // ── apimapper_connection_get ───────────────────────────────────────
@@ -99,20 +217,33 @@ export function registerConnectionTools(server) {
         inputSchema: {
             id: z.string().describe('Connection ID (e.g., "conn_Mz33OVPF1z3ap8fbbQtpx"). Use apimapper_connection_list.'),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Get Connection", openWorld: true }),
     }, async ({ id }) => {
         // PHP wraps via fromControllerResponse($response, 'connection') →
         // `{success:true, connection:{…}}`. Unwrap defensively so a future
         // flatten on the PHP side doesn't break us. Audit: F-A1-01.
         const r = await request(`/connections/${encodeURIComponent(id)}`);
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return errorResult({
+                message: r.error ?? "connection get failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { id },
+            });
         }
         const conn = unwrapEntity(r.data, "connection");
         if (!conn || Object.keys(conn).length === 0) {
-            return formatResult({ error: "connection not found", status: r.status, context: { id }, hint: hintFor("not_found") }, true);
+            return errorResult({
+                message: "connection not found",
+                code: r.status ? String(r.status) : "not_found",
+                suggestion: hintFor("not_found"),
+                details: { id },
+            });
         }
-        return formatResult(conn, false, { maxChars: 4000 });
+        // 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);
     });
     // ── apimapper_connection_create ────────────────────────────────────
     server.registerTool("apimapper_connection_create", {
@@ -129,29 +260,92 @@ export function registerConnectionTools(server) {
             cache_ttl: z.number().int().min(0).default(3600).describe("Cache TTL in seconds (snake_case wire key)"),
             description: z.string().optional().describe("Free-text description"),
         },
-        annotations: creating(),
+        annotations: creating({ title: "Create Connection", openWorld: true }),
     }, async (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
+        // candidate-list error. auth_type "none" never needs a credential.
+        let resolvedInput = { ...input };
+        if (input.auth_type !== "none" && !input.credential_id) {
+            const lr = await request("/credentials", {}, { sanitize: true });
+            if (!lr.success) {
+                return errorResult({
+                    message: lr.error ?? "credential lookup failed",
+                    code: lr.errorCode ?? (lr.status ? String(lr.status) : undefined),
+                    suggestion: hintFor(lr.errorCode),
+                    details: { name: input.name, auth_type: input.auth_type },
+                });
+            }
+            const creds = Array.isArray(lr.data?.credentials) ? lr.data.credentials : [];
+            if (creds.length === 0) {
+                return errorResult({
+                    message: `auth_type "${input.auth_type}" needs a credential, but none are stored.`,
+                    code: "credential_not_found",
+                    suggestion: "Create one with apimapper_credential_create, then retry with its credential_id.",
+                    details: { name: input.name, auth_type: input.auth_type },
+                });
+            }
+            if (creds.length === 1) {
+                resolvedInput = { ...input, credential_id: creds[0].id };
+            }
+            else {
+                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 };
+            }
+        }
         // PHP fromControllerResponse(_, 'connection', 201) → {success, connection:{…}}.
         // Audit: F-A1-02.
         const r = await request("/connections", {
             method: "POST",
-            body: JSON.stringify(input),
+            body: JSON.stringify(resolvedInput),
         });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { name: input.name, endpoint: input.endpoint },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return errorResult({
+                message: r.error ?? "connection create failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { name: input.name, endpoint: input.endpoint },
+            });
         }
         const conn = unwrapEntity(r.data, "connection");
+        // F-3.2 (Pass-1 consolidation) — mutating-tool payload-shape rationale.
+        //
+        // connection_create + connection_update stay on the flat
+        // `formatResult({ ... })` shape rather than migrating to the
+        // structured detailResult / actionResult builders. The mutating-tool
+        // payload here is intentionally minimal (the wire echo confirms the
+        // op + identity), and the detail builders are tuned for fully
+        // populated entities (badge/group/entry layouts) — wrapping a 3-field
+        // confirmation in a Rich Card would add noise without surfacing more
+        // information. This mirrors the connection_data passthrough rationale:
+        // the LLM benefits from the bare structured echo; UI hosts that want
+        // a richer view re-fetch via connection_get. IA-10 uniformity is
+        // restored via `next_steps[]` (array, single-element) below.
         return formatResult({
             created: true,
             id: conn?.id,
             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.",
+            ],
         }, false, { maxChars: 2000 });
     });
     // ── apimapper_connection_update ────────────────────────────────────
@@ -167,7 +361,7 @@ export function registerConnectionTools(server) {
                 'Examples: {"name":"Renamed"}, {"cache_ttl":7200}, {"endpoint":"/v2/posts"}, ' +
                 '{"credential_id":"cred_xxx"}'),
         },
-        annotations: mutating(),
+        annotations: mutating({ title: "Update Connection", openWorld: true }),
     }, async ({ id, patch }) => {
         // PHP fromControllerResponse(_, 'connection') → {success, connection:{…}}.
         // Audit: F-A1-03.
@@ -176,10 +370,25 @@ export function registerConnectionTools(server) {
             body: JSON.stringify(patch),
         });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return errorResult({
+                message: r.error ?? "connection update failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { id },
+            });
         }
         const conn = unwrapEntity(r.data, "connection");
-        return formatResult({ updated: true, id: conn?.id, name: conn?.name }, false, { maxChars: 2000 });
+        // F-3.2 (Pass-1 consolidation) — see connection_create for the
+        // mutating-tool payload-shape rationale. next_steps[] restored for
+        // IA-10 uniformity (single-element array, not flat `next:`).
+        return formatResult({
+            updated: true,
+            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.",
+            ],
+        }, false, { maxChars: 2000 });
     });
     // ── apimapper_connection_delete ────────────────────────────────────
     server.registerTool("apimapper_connection_delete", {
@@ -194,7 +403,7 @@ export function registerConnectionTools(server) {
                 .default(false)
                 .describe("Must be true to execute. On confirm:false, returns a preview."),
         },
-        annotations: destructive(),
+        annotations: destructive({ title: "Delete Connection", openWorld: true }),
     }, async ({ id, confirm }) => {
         if (!confirm) {
             // PHP fromControllerResponse(_, 'connection') wraps as
@@ -218,7 +427,12 @@ export function registerConnectionTools(server) {
         }
         const r = await request(`/connections/${encodeURIComponent(id)}`, { method: "DELETE" });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return errorResult({
+                message: r.error ?? "connection delete failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { id },
+            });
         }
         return formatResult({ deleted: true, id }, false, { maxChars: 1500 });
     });
@@ -231,33 +445,30 @@ export function registerConnectionTools(server) {
         inputSchema: {
             id: z.string().describe("Connection ID. Use apimapper_connection_list to find."),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Test Connection", openWorld: true }),
     }, async ({ id }) => {
+        // PHP wraps probe fields one level deeper:
+        //   {success:true, data:{actionType, http_code, duration_ms, body_preview, …}, items_count}
+        // unwrapInnerSuccess sees outer success:true and lets it through, but
+        // probe fields still live under `data.data.*`. Audit: F-A1-05.
         const r = await request("/connections/test", { method: "POST", body: JSON.stringify({ connection_id: id }) }, { unwrapInnerSuccess: true });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                payloadFailed: r.payloadFailed,
-                context: { id },
-                hint: r.payloadFailed
+            return errorResult({
+                message: r.error ?? "connection test failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: r.payloadFailed
                     ? "Probe ran but reported failure — check the upstream API status, credentials, or connection endpoint."
                     : hintFor(r.errorCode),
-            }, true);
+                details: { id, payloadFailed: r.payloadFailed },
+            });
         }
         // Defensive unwrap: prefer `r.data.data` if present, fall back to `r.data` itself
         // so a future PHP flatten doesn't break this tool.
         const outer = (r.data && typeof r.data === "object" ? r.data : {});
         const probe = (outer.data && typeof outer.data === "object" ? outer.data : outer);
-        return formatResult({
-            ok: true,
-            id,
-            actionType: probe.actionType ?? "ok",
-            http_code: probe.http_code,
-            duration_ms: probe.duration_ms,
-            body_preview: probe.body_preview?.slice(0, 500),
-        }, false, { maxChars: 2500 });
+        // W3.1 — statsResult: the probe outcome is a small flat scalar set.
+        // IA-10: the follow-up guidance rides in the stats description.
+        return buildConnectionTestStats(id, probe);
     });
     // ── apimapper_connection_health_check ──────────────────────────────
     server.registerTool("apimapper_connection_health_check", {
@@ -271,20 +482,24 @@ export function registerConnectionTools(server) {
                 .default([])
                 .describe('Connection IDs to probe (empty = all). REST wire-key: connection_ids.'),
         },
-        annotations: readOnly(),
-    }, async ({ connection_ids }) => {
+        annotations: readOnly({ title: "Connection Health Check", openWorld: true }),
+    }, async ({ connection_ids }, extra) => {
+        // W3.5 — coarse progress side-channel. `null` when the caller sent no
+        // progressToken; `progress?.report(...)` then no-ops. The batch probe
+        // can take 10-30s, so a start/done signal keeps the caller informed.
+        const progress = extra ? createProgressReporter(extra) : null;
+        await progress?.report(0, 1, "Probing connections…");
         const r = await request("/connections/health-check", {
             method: "POST",
             body: JSON.stringify({ connection_ids }),
         });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { count: connection_ids.length },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return errorResult({
+                message: r.error ?? "connection health check failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { count: connection_ids.length },
+            });
         }
         const data = (r.data && typeof r.data === "object") ? r.data : {};
         // PHP returns map keyed by connection id, NOT under a 'results' key —
@@ -297,71 +512,143 @@ export function registerConnectionTools(server) {
             const o = x;
             return o.success === true || o.actionType === "ok";
         }).length;
-        return formatResult({
-            ok_count: okCount,
-            fail_count: results.length - okCount,
-            total: results.length,
-            results: data,
-        }, false, { maxChars: 6000 });
+        await progress?.report(1, 1, `Probed ${results.length} connection(s)`);
+        // W3.1 — statsResult: the batch outcome is a counts dashboard.
+        // IA-10: the description routes the AI to connection_test for the
+        // per-connection probe detail (the full result map is too large for
+        // a stat grid).
+        return buildHealthCheckStats(okCount, results.length - okCount, results.length);
     });
     // ── apimapper_connection_data ──────────────────────────────────────
+    // rc.10.1 C (2026-05-19) — exposes `limit` + `offset` to AI agents so
+    // they can constrain large API responses without injecting template
+    // hacks like `template_fields.per_page`. Trim happens IN-MEMORY on
+    // the TS side after the response is unwrapped — this is single-shot
+    // upstream, no multi-page fetch is triggered. Real cursor / page-loop
+    // pagination is a separate roadmap item (see plan Section E1).
     server.registerTool("apimapper_connection_data", {
         title: "Fetch Connection Sample Data",
         description: "Fetch sample data from a connection's configured endpoint. The PHP handler reads ALL " +
-            "query params as source-context for template substitution." +
-            "\n\nExample:\n  apimapper_connection_data({ id: 'con_abc123', params: { query: 'nature', per_page: 10 } })",
+            "query params as source-context for template substitution. Use `limit`/`offset` to trim " +
+            "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\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" +
+            "  apimapper_connection_data({ id: 'con_abc123', fields: ['title', 'image.url'] })  // 2 leaf keys per item\n" +
+            "  apimapper_connection_data({ id: 'con_abc123', template_fields: { query: 'nature' } })",
         inputSchema: {
             id: z.string().describe("Connection ID. Use apimapper_connection_list to find."),
-            endpoint: z.string().optional().describe('Override endpoint (e.g., "Scheduled Events")'),
+            endpoint: z
+                .string()
+                .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.'),
             template_fields: z
-                .record(z.string(), z.string())
+                .record(z.string(), z.union([z.string(), z.number().finite(), z.boolean()]))
                 .optional()
-                .describe('Template field values flattened into query string (e.g., {"spreadsheet_id":"...","user_uri":"..."})'),
+                .describe('Template field values flattened into the query string. Accepts string/number/boolean values; non-string values are stringified via JS String() (number 25 → "25", true → "true", false → "false"). NaN/Infinity numbers are rejected by schema (defense-in-depth). Nested objects/arrays are rejected. Example: { spreadsheet_id: "abc", per_page: 25, active: true } → ?spreadsheet_id=abc&per_page=25&active=true'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("Trim the returned items array to at most N (1-500). Applied in-memory after the upstream fetch — does NOT request fewer items from the source API. Omit to return the full response."),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Skip the first N items before applying `limit`. Applied in-memory. Useful for inspecting later items in a large response when combined with `limit`."),
+            // rc.13 W3.3 (2026-05-20) — optional per-item field whitelist.
+            // When the data payload is an array of objects each item is mapped
+            // through pickFields() so only the named leaf keys survive.
+            fields: z
+                .array(z.string().min(1))
+                .max(40)
+                .optional()
+                .describe("Optional whitelist of fields to keep per item (supports nested paths like 'image.url'). Default: all fields. Cuts response size on sparse queries — e.g. fields:['title','image.url'] keeps only those two leaf keys per record."),
         },
-        annotations: readOnly(),
-    }, async ({ id, endpoint, template_fields }) => {
+        annotations: readOnly({ title: "Get Connection Data", openWorld: true }),
+    }, async ({ id, endpoint, template_fields, limit, offset, fields }) => {
         const params = new URLSearchParams();
         if (endpoint)
             params.set("endpoint", endpoint);
         // Flatten template_fields directly as query params — PHP handler does
         // array_filter() across get_query_params() and uses each key as a
-        // template variable.
+        // template variable. Non-string primitives (number/boolean — F-10/W1.5)
+        // are explicitly stringified via String(): the schema admits
+        // string|number|boolean unions, so the handler must canonicalise
+        // numbers to their decimal repr ("25") and booleans to "true"/"false"
+        // before they hit URLSearchParams. URLSearchParams.set would coerce
+        // 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)) {
-                params.set(k, v);
+                params.set(k, typeof v === "string" ? v : String(v));
             }
         }
         const qs = params.toString();
         const r = await request(`/connections/${encodeURIComponent(id)}/data${qs ? `?${qs}` : ""}`);
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { id, endpoint, template_fields },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return errorResult({
+                message: r.error ?? "connection data fetch failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { id, endpoint, template_fields, limit, offset },
+            });
         }
         // PHP success body: {data:[…items…], connection, body?, content_type?, status?}.
         // Operate on the inner `data` payload, not on the envelope. Surface
         // `body`/`content_type` for the non-JSON path. Audit: F-A1-06.
         const envelope = (r.data && typeof r.data === "object" ? r.data : {});
-        const inner = "data" in envelope ? envelope.data : envelope;
+        const innerRaw = "data" in envelope ? envelope.data : envelope;
         const body = typeof envelope.body === "string" ? envelope.body : undefined;
         const contentType = typeof envelope.content_type === "string" ? envelope.content_type : undefined;
-        const isArray = Array.isArray(inner);
-        const items = isArray
-            ? inner
-            : inner && typeof inner === "object" && Array.isArray(inner.items)
-                ? inner.items
-                : null;
+        // rc.10.1 C + rc.13 W1.2 (F-01+F-38) — apply in-memory trim via
+        // extracted pure function. See the `applyTrim` JSDoc in
+        // connections-trim.ts for the shape-detection contract and
+        // shallow-clone guarantees.
+        const trim = applyTrim(innerRaw, limit, offset);
+        // rc.13 W3.3 — optional field-projection. Runs AFTER trim: the
+        // trimmed slice is the smallest correct surface to project, and
+        // projection composes cleanly on top of it (project-of-trimmed ≡
+        // narrowing a smaller list). Projection is applied ONLY when the
+        // (trimmed) payload is an array of plain objects — each item is
+        // mapped through pickFields(), which flattens nested paths to leaf
+        // keys and silently drops missing fields. For every other shape
+        // (single object, scalar, nested-items envelope, array of
+        // primitives) projection is skipped and the payload passes through
+        // unchanged — there is no per-record surface to whitelist there, so
+        // narrowing would be lossy or meaningless. `projected_fields` is
+        // still echoed back in the envelope whenever `fields` was supplied,
+        // so the AI client always knows projection was requested even when
+        // the shape made it a no-op.
+        let projectedPayload = trim.payload;
+        if (fields && Array.isArray(trim.payload)) {
+            projectedPayload = trim.payload.map((item) => item !== null && typeof item === "object" && !Array.isArray(item)
+                ? pickFields(item, fields)
+                : item);
+        }
         return formatResult({
             ok: true,
-            shape: isArray ? "array" : typeof inner,
-            item_count: items ? items.length : undefined,
+            // F-38 — surface a stable, narrow shape enum instead of typeof.
+            // "object" is preserved for the legacy non-iterable case so
+            // existing wire-shape pins keep working.
+            shape: trim.detectedShape === "other" ? typeof trim.payload : trim.detectedShape,
+            item_count: trim.itemCount,
+            ...(trim.trimmed && trim.totalBeforeTrim !== undefined
+                ? { total_before_trim: trim.totalBeforeTrim, trimmed: true }
+                : {}),
+            // W3.3 — echo the requested whitelist so the AI knows the
+            // per-item shape was (or was meant to be) reduced.
+            ...(fields ? { projected_fields: fields } : {}),
             body,
             content_type: contentType,
-            payload: inner,
+            payload: projectedPayload,
         }, false, { maxChars: 6000 });
     });
     // ── apimapper_connection_resources ─────────────────────────────────
@@ -375,9 +662,15 @@ export function registerConnectionTools(server) {
             field: z
                 .string()
                 .describe('Resource-picker field name (e.g., "spreadsheet_id", "drive_file_id"). REST wire-key: field.'),
-            query: z.string().optional().describe("Free-text search query"),
+            // 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
+            // min(3) (stricter is OK, less regression-risk). Pin-test in
+            // connections.test.ts "F-29 connection_resources query min length pin"
+            // guards against loosening.
+            query: z.string().min(3).optional().describe("Free-text search query. Must be 3+ characters — single-char and 2-char probes are blocked because the resource lists are small enough to scan without typeahead."),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "List Connection Resources", openWorld: true }),
     }, async ({ id, field, query }) => {
         const params = new URLSearchParams();
         params.set("field", field);
@@ -385,29 +678,35 @@ export function registerConnectionTools(server) {
             params.set("query", query);
         const r = await request(`/connections/${encodeURIComponent(id)}/resources?${params.toString()}`);
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { id, field, query },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return errorResult({
+                message: r.error ?? "connection resources failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { id, field, query },
+            });
         }
-        const data = r.data;
-        const resources = Array.isArray(data)
-            ? data
-            : data && typeof data === "object" && Array.isArray(data.resources)
-                ? data.resources
-                : data && typeof data === "object" && Array.isArray(data.items)
-                    ? data.items
-                    : [];
-        return formatResult({
-            field,
-            query: query || null,
-            resource_count: resources.length,
-            resources: resources.slice(0, 100),
-            note: resources.length > 100 ? `Showing first 100 of ${resources.length} resources.` : undefined,
-        }, false, { maxChars: 6000 });
+        // A1-P3-1: pure helper handles the three wire-shapes (bare array,
+        // `{ resources }`, `{ items }`) + fallback to `[]` for unknown
+        // shapes. Pinned per-branch in connections.test.ts.
+        const resources = extractResourceList(r.data);
+        // W3.1 — tableResult: resources are a flat row list. IA-7: opaque id
+        // stays llmOnly. IA-10: the footer carries the next-step guidance and
+        // the truncation note when more than 100 resources are returned.
+        const truncated = resources.length > 100;
+        const footerLines = [
+            `Picker field: ${field}${query ? ` · filter: "${query}"` : ""}.`,
+        ];
+        if (truncated) {
+            footerLines.push(`Showing first 100 of ${resources.length} resources — narrow with the query filter.`);
+        }
+        footerLines.push("Next: pass a chosen resource ID into apimapper_connection_update " +
+            "({ id, patch }) or the connection's pipeline default_params.");
+        return tableResult(resources.slice(0, 100), {
+            columns: RESOURCE_TABLE_COLUMNS,
+            map: mapResourceRow,
+            header: (n) => `${n} resources on ${id}`,
+            footer: footerLines.join("\n"),
+        });
     });
     // ── apimapper_connection_pipeline_update ───────────────────────────
     server.registerTool("apimapper_connection_pipeline_update", {
@@ -420,7 +719,7 @@ export function registerConnectionTools(server) {
                 .record(z.string(), z.unknown())
                 .describe('Pipeline JSON (e.g., {"endpoints":[...], "items_path":"data", "items_shape":"flat"})'),
         },
-        annotations: mutating(),
+        annotations: mutating({ title: "Update Connection Pipeline", openWorld: true }),
     }, async ({ id, pipeline }) => {
         // PHP ConnectionPipelineHandler uses fromControllerResponse(_, 'connection')
         // → {success, connection:{…}}. Unwrap defensively. Audit: F-A1-07.
@@ -429,7 +728,12 @@ export function registerConnectionTools(server) {
             body: JSON.stringify(pipeline),
         });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return errorResult({
+                message: r.error ?? "connection pipeline update failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { id },
+            });
         }
         const conn = unwrapEntity(r.data, "connection");
         return formatResult({ updated: true, id: conn?.id, name: conn?.name }, false, { maxChars: 2000 });