@papi-ai/server 0.7.71 → 0.7.73

package/dist/backfill-cycle-metrics.js

@@ -1621,6 +1621,13 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       insertPlanRun(entry) {
         return this.invoke("insertPlanRun", [entry]);
       }
+      /** task-2940: forwarded per-tool telemetry write. Requires the deployed
+       *  data-proxy to carry the matching `insertToolRun` case — until that deploy
+       *  lands, hosted callers fail this invoke and the caller swallows it (telemetry
+       *  must never fail a tool call). */
+      insertToolRun(entry) {
+        return this.invoke("insertToolRun", [entry]);
+      }
       getCostSummary(cycleNumber) {
         return this.invoke("getCostSummary", [cycleNumber]);
       }

package/dist/index.js

@@ -1738,6 +1738,13 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       insertPlanRun(entry) {
         return this.invoke("insertPlanRun", [entry]);
       }
+      /** task-2940: forwarded per-tool telemetry write. Requires the deployed
+       *  data-proxy to carry the matching `insertToolRun` case — until that deploy
+       *  lands, hosted callers fail this invoke and the caller swallows it (telemetry
+       *  must never fail a tool call). */
+      insertToolRun(entry) {
+        return this.invoke("insertToolRun", [entry]);
+      }
       getCostSummary(cycleNumber) {
         return this.invoke("getCostSummary", [cycleNumber]);
       }
@@ -11207,6 +11214,55 @@ function formatBlockerWaiting(blocker) {
   }
 }
 
+// src/lib/tool-telemetry.ts
+var INSTRUMENTED_TOOLS = /* @__PURE__ */ new Set([
+  "plan",
+  "orient",
+  "build_execute",
+  "review_submit",
+  "release",
+  "strategy_review"
+]);
+var WRAPPER_INSTRUMENTED_TOOLS = new Set(
+  [...INSTRUMENTED_TOOLS].filter((t) => t !== "plan")
+);
+var PLAN_PREPARE_TOOL_NAME = "plan:prepare";
+function measureResultBytes(content) {
+  let total = 0;
+  for (const part of content) {
+    if (typeof part.text === "string") total += Buffer.byteLength(part.text, "utf-8");
+  }
+  return total;
+}
+function recordToolRun(adapter2, sample) {
+  if (sample.toolName !== PLAN_PREPARE_TOOL_NAME && !WRAPPER_INSTRUMENTED_TOOLS.has(sample.toolName)) return;
+  if (typeof adapter2.insertToolRun !== "function") return;
+  try {
+    const promise = adapter2.insertToolRun({
+      toolName: sample.toolName,
+      contextBytes: sample.contextBytes,
+      durationMs: sample.durationMs,
+      cycleNumber: sample.cycleNumber ?? null,
+      source: "mcp-server"
+    });
+    if (promise && typeof promise.catch === "function") {
+      promise.catch((err) => {
+        console.error(`[telemetry] insertToolRun failed (non-blocking): ${err instanceof Error ? err.message : String(err)}`);
+      });
+    }
+  } catch (err) {
+    console.error(`[telemetry] insertToolRun threw (non-blocking): ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function recordPlanPrepareRun(adapter2, sample) {
+  recordToolRun(adapter2, {
+    toolName: PLAN_PREPARE_TOOL_NAME,
+    contextBytes: sample.contextBytes,
+    durationMs: sample.durationMs,
+    cycleNumber: sample.cycleNumber ?? null
+  });
+}
+
 // src/lib/visibility-inheritance.ts
 var TIER_RANK = {
   public: 0,
@@ -13000,6 +13056,7 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
     console.error(`[plan-perf] contextBytes=${contextBytes2} (handoffs-only)`);
     const planSystemPrompt2 = await getPrompt("plan-system");
     await recordPlanGenerationActive(tracker, incomingCycle);
+    recordPlanPrepareRun(adapter2, { contextBytes: contextBytes2, durationMs: totalMs2, cycleNumber: incomingCycle });
     return {
       mode: "full",
       // apply phase treats it the same
@@ -13061,6 +13118,7 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
   }
   const planSystemPrompt = await getPrompt("plan-system");
   await recordPlanGenerationActive(tracker, incomingCycle);
+  recordPlanPrepareRun(adapter2, { contextBytes, durationMs: totalMs, cycleNumber: incomingCycle });
   return {
     mode,
     cycleNumber,
@@ -16918,7 +16976,9 @@ async function viewBoard(adapter2, phaseFilter, options) {
     total,
     returned: paged.length,
     offset,
-    hasMore: offset + paged.length < total
+    hasMore: offset + paged.length < total,
+    totalUnfiltered: allTasks.length,
+    limit
   };
 }
 async function viewBoardSummary(adapter2) {
@@ -16966,7 +17026,87 @@ async function archiveTasks(adapter2, phases, statuses) {
   return { archivedCount: result.archivedCount, phases };
 }
 
+// src/lib/projection.ts
+function resolveFields(raw, allowed, toolName) {
+  if (raw === void 0 || raw === null) return { ok: true, fields: null };
+  if (typeof raw !== "string") {
+    return { ok: false, error: `${toolName}: fields must be a comma-separated string (got ${typeof raw}).` };
+  }
+  const trimmed = raw.trim();
+  if (trimmed === "") return { ok: true, fields: null };
+  const canonical = new Map(allowed.map((a) => [a.toLowerCase(), a]));
+  const requested = [];
+  for (const part of trimmed.split(",")) {
+    const token = part.trim();
+    if (token === "") continue;
+    const hit = canonical.get(token.toLowerCase());
+    if (!hit) {
+      return {
+        ok: false,
+        error: `${toolName}: unknown field "${token}". Allowed fields: ${allowed.join(", ")}.`
+      };
+    }
+    if (!requested.includes(hit)) requested.push(hit);
+  }
+  if (requested.length === 0) return { ok: true, fields: null };
+  if (!requested.includes("id")) requested.unshift("id");
+  return { ok: true, fields: requested };
+}
+function selectColumns(columns, fields) {
+  if (!fields) return columns;
+  const byName = new Map(columns.map((c) => [c.name, c]));
+  return fields.map((f) => byName.get(f)).filter((c) => c !== void 0);
+}
+function wantsMeta(raw) {
+  return raw === true || raw === "true";
+}
+function formatMeta(meta) {
+  return `**meta:** ${JSON.stringify(meta)}`;
+}
+function withMeta(body, meta) {
+  return meta ? `${body}
+
+${formatMeta(meta)}` : body;
+}
+function pad(value, width) {
+  return value.length >= width ? value : value + " ".repeat(width - value.length);
+}
+function renderTable(headers, rows) {
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const headerLine = headers.map((h, i) => pad(h, widths[i])).join(" | ");
+  const separator = widths.map((w) => "-".repeat(w)).join(" | ");
+  const dataLines = rows.map((row) => row.map((cell, i) => pad(cell, widths[i])).join(" | "));
+  return [headerLine, separator, ...dataLines].join("\n");
+}
+
 // src/tools/board.ts
+var BOARD_COLUMNS = [
+  { name: "priority", header: "Priority", value: (t) => t.priority },
+  { name: "id", header: "Task", value: (t) => t.id },
+  { name: "title", header: "Summary", value: (t) => truncateTitle(t.title) },
+  { name: "status", header: "Status", value: (t) => t.status },
+  { name: "cycle", header: "Cycle", value: (t) => t.cycle != null ? String(t.cycle) : "-" },
+  { name: "phase", header: "Phase", value: (t) => t.phase ?? "-" },
+  { name: "module", header: "Module", value: (t) => t.module ?? "-" },
+  { name: "epic", header: "Epic", value: (t) => t.epic ?? "-" },
+  { name: "complexity", header: "Effort", value: (t) => t.complexity ?? "-" },
+  { name: "createdAt", header: "Created", value: (t) => t.createdAt ?? "-" },
+  { name: "source", header: "Source", value: (t) => t.source ?? "-" }
+];
+var BOARD_FIELDS = BOARD_COLUMNS.map((c) => c.name);
+var BOARD_SINGLE_LABELS = {
+  id: "Task",
+  title: "Title",
+  status: "Status",
+  priority: "Priority",
+  cycle: "Cycle",
+  phase: "Phase",
+  module: "Module",
+  epic: "Epic",
+  complexity: "Effort",
+  createdAt: "Created",
+  source: "Source"
+};
 var boardViewTool = {
   name: "board_view",
   description: 'View the Board. To find a SPECIFIC task or subset, FILTER FIRST \u2014 do not dump the whole board: pass task_id for one task (full detail), query="<text>" for a title/notes substring match, or cycle=<n> for one cycle. Combine with status/phase. By default shows active tasks only (excludes Done/Cancelled), sorted by priority, limited to 50; titles are truncated in the table (single-task lookup shows the full title). Use status="all" to see everything, mode="summary" for counts only. Does not call the Anthropic API.',
@@ -17011,6 +17151,14 @@ var boardViewTool = {
         type: "string",
         enum: ["full", "summary"],
         description: 'Output mode: "full" (default) shows task table, "summary" shows counts only.'
+      },
+      fields: {
+        type: "string",
+        description: `Optional sparse-field projection \u2014 comma-separated column names, e.g. "title,status". Returns ONLY those columns (id is always included so rows stay addressable) which is far cheaper on session context than the full table. Allowed: ${BOARD_FIELDS.join(", ")}. An unknown name is an error.`
+      },
+      meta: {
+        type: "boolean",
+        description: "Append a {total, filtered, returned, limit, offset} envelope so you can tell a truncated result from a complete one. Default false."
       }
     },
     required: []
@@ -17175,14 +17323,27 @@ var boardEditTool = {
     required: ["task_id"]
   }
 };
-function pad(value, width) {
-  return value.length >= width ? value : value + " ".repeat(width - value.length);
-}
 var TITLE_MAX = 80;
 function truncateTitle(title) {
   return title.length > TITLE_MAX ? `${title.slice(0, TITLE_MAX - 1)}\u2026` : title;
 }
-function formatSingleTask(t) {
+function formatSingleTask(t, fields) {
+  if (fields) {
+    const values2 = {
+      id: t.id,
+      title: t.title,
+      status: t.status,
+      priority: t.priority,
+      cycle: t.cycle != null ? String(t.cycle) : "-",
+      phase: t.phase ?? "-",
+      module: t.module ?? "-",
+      epic: t.epic ?? "-",
+      complexity: t.complexity ?? "-",
+      createdAt: t.createdAt ?? "-",
+      source: t.source ?? "-"
+    };
+    return fields.map((f) => `- **${BOARD_SINGLE_LABELS[f] ?? f}:** ${values2[f]}`).join("\n");
+  }
   const lines = [
     `**${t.id} \u2014 ${t.title}**`,
     "",
@@ -17199,41 +17360,20 @@ function formatSingleTask(t) {
   if (t.why?.trim()) lines.push(`- **Why:** ${t.why.trim()}`);
   return lines.join("\n");
 }
-function formatBoard(result) {
+function formatBoard(result, fields) {
   if (result.tasks.length === 0) {
     return "No tasks found.";
   }
-  const headers = ["Priority", "Task", "Summary", "Status", "Cycle", "Phase", "Module", "Epic", "Effort", "Created", "Source"];
-  const rows = result.tasks.map((t) => [
-    t.priority,
-    t.id,
-    truncateTitle(t.title),
-    t.status,
-    t.cycle != null ? String(t.cycle) : "-",
-    t.phase ?? "-",
-    t.module ?? "-",
-    t.epic ?? "-",
-    t.complexity ?? "-",
-    t.createdAt ?? "-",
-    t.source ?? "-"
-  ]);
-  const widths = headers.map(
-    (h, i) => Math.max(h.length, ...rows.map((r) => r[i].length))
-  );
-  const headerLine = headers.map((h, i) => pad(h, widths[i])).join(" | ");
-  const separator = widths.map((w) => "-".repeat(w)).join(" | ");
-  const dataLines = rows.map(
-    (row) => row.map((cell, i) => pad(cell, widths[i])).join(" | ")
-  );
+  const columns = selectColumns(BOARD_COLUMNS, fields);
+  const headers = columns.map((c) => c.header);
+  const rows = result.tasks.map((t) => columns.map((c) => c.value(t)));
   const lines = [];
   lines.push(`**${result.returned} of ${result.total} tasks**`);
   if (result.hasMore) {
     lines.push(`_Showing ${result.offset + 1}\u2013${result.offset + result.returned}. Use offset=${result.offset + result.returned} to see more._`);
   }
   lines.push("");
-  lines.push(headerLine);
-  lines.push(separator);
-  lines.push(...dataLines);
+  lines.push(renderTable(headers, rows));
   return lines.join("\n");
 }
 function formatSummary(summary) {
@@ -17255,15 +17395,21 @@ function formatSummary(summary) {
 }
 async function handleBoardView(adapter2, args) {
   const mode = args.mode;
+  const projection = resolveFields(args.fields, BOARD_FIELDS, "board_view");
+  if (!projection.ok) return errorResponse(projection.error);
+  const fields = projection.fields;
+  const emitMeta = wantsMeta(args.meta);
   if (mode === "summary") {
     const summary = await viewBoardSummary(adapter2);
-    return textResponse(formatSummary(summary));
+    const meta2 = emitMeta ? { total: summary.total, filtered: summary.total, returned: summary.total, limit: null, offset: 0 } : null;
+    return textResponse(withMeta(formatSummary(summary), meta2));
   }
   const taskIdArg = args.task_id ?? args.display_id;
   if (taskIdArg) {
     const task = await adapter2.getTask(taskIdArg);
     if (!task) return errorResponse(`Task ${taskIdArg} not found.`);
-    return textResponse(formatSingleTask(task));
+    const meta2 = emitMeta ? { total: 1, filtered: 1, returned: 1, limit: null, offset: 0 } : null;
+    return textResponse(withMeta(formatSingleTask(task, fields), meta2));
   }
   const result = await viewBoard(adapter2, void 0, {
     phase: args.phase,
@@ -17273,17 +17419,26 @@ async function handleBoardView(adapter2, args) {
     query: args.query,
     cycle: args.cycle
   });
-  let output = formatBoard(result);
-  try {
-    const comments = await adapter2.getRecentTaskComments?.(30);
-    if (comments && comments.length > 0) {
-      const taskIds = new Set(result.tasks.map((t) => t.id));
-      const section = formatTaskComments(comments, taskIds, "**Task Comments:**");
-      if (section) output += "\n" + section;
+  let output = formatBoard(result, fields);
+  if (!fields) {
+    try {
+      const comments = await adapter2.getRecentTaskComments?.(30);
+      if (comments && comments.length > 0) {
+        const taskIds = new Set(result.tasks.map((t) => t.id));
+        const section = formatTaskComments(comments, taskIds, "**Task Comments:**");
+        if (section) output += "\n" + section;
+      }
+    } catch {
     }
-  } catch {
   }
-  return textResponse(output);
+  const meta = emitMeta ? {
+    total: result.totalUnfiltered,
+    filtered: result.total,
+    returned: result.returned,
+    limit: result.limit,
+    offset: result.offset
+  } : null;
+  return textResponse(withMeta(output, meta));
 }
 async function handleBoardDeprioritise(adapter2, args) {
   const taskId = args.task_id;
@@ -21530,7 +21685,7 @@ async function listBuilds(adapter2, config2) {
   ]);
   const currentCycle = health?.totalCycles ?? 0;
   if (tasks.length === 0) {
-    return { sorted: [], inProgress: [], backlog: [], blocked: [], warnings, isEmpty: true, noHandoffs: false, currentCycle };
+    return { sorted: [], inProgress: [], backlog: [], blocked: [], warnings, isEmpty: true, noHandoffs: false, currentCycle, totalTasks: tasks.length };
   }
   const withHandoff = tasks.filter((t) => {
     if (!t.buildHandoff) return false;
@@ -21541,7 +21696,7 @@ async function listBuilds(adapter2, config2) {
     return true;
   });
   if (withHandoff.length === 0) {
-    return { sorted: [], inProgress: [], backlog: [], blocked: [], warnings, isEmpty: false, noHandoffs: true, currentCycle };
+    return { sorted: [], inProgress: [], backlog: [], blocked: [], warnings, isEmpty: false, noHandoffs: true, currentCycle, totalTasks: tasks.length };
   }
   const buildable = [];
   const blocked = [];
@@ -21556,7 +21711,7 @@ async function listBuilds(adapter2, config2) {
   const inProgress = buildable.filter((t) => t.status === "In Progress");
   const backlog = buildable.filter((t) => t.status !== "In Progress");
   const sorted = [...inProgress, ...backlog];
-  return { sorted, inProgress, backlog, blocked, warnings, isEmpty: false, noHandoffs: sorted.length === 0 && blocked.length === 0, currentCycle };
+  return { sorted, inProgress, backlog, blocked, warnings, isEmpty: false, noHandoffs: sorted.length === 0 && blocked.length === 0, currentCycle, totalTasks: tasks.length };
 }
 async function describeTask(adapter2, taskId) {
   const task = await adapter2.getTask(taskId);
@@ -22976,6 +23131,17 @@ async function handleDocReorder(adapter2, args) {
 
 // src/tools/build.ts
 init_git();
+var BUILD_LIST_COLUMNS = [
+  { name: "id", header: "Task", value: (t) => t.id },
+  { name: "title", header: "Summary", value: (t) => t.title },
+  { name: "status", header: "Status", value: (t) => t.status },
+  { name: "priority", header: "Priority", value: (t) => t.priority },
+  { name: "complexity", header: "Effort", value: (t) => t.complexity ?? "-" },
+  { name: "module", header: "Module", value: (t) => t.module ?? "-" },
+  { name: "epic", header: "Epic", value: (t) => t.epic ?? "-" },
+  { name: "cycle", header: "Cycle", value: (t) => t.cycle != null ? String(t.cycle) : "-" }
+];
+var BUILD_LIST_FIELDS = BUILD_LIST_COLUMNS.map((c) => c.name);
 var buildListTool = {
   name: "build_list",
   description: "List cycle tasks that have BUILD HANDOFFs ready for execution. Shows task ID, title, status, priority, and complexity. In Progress tasks appear first, then Backlog. Does not call the Anthropic API.",
@@ -22985,7 +23151,16 @@ var buildListTool = {
     properties: {
       limit: {
         type: "integer",
-        description: "Optional maximum number of tasks to return per section. Omit to return all. Reserved for future pagination \u2014 current behaviour returns all matching tasks regardless of value."
+        minimum: 1,
+        description: "Optional maximum number of tasks to return per section (In Progress / Backlog / Blocked). Omit to return all."
+      },
+      fields: {
+        type: "string",
+        description: `Optional sparse-field projection \u2014 comma-separated column names, e.g. "title,status". Returns a compact table of ONLY those columns (id is always included) instead of the full per-task block, which is far cheaper on session context. Allowed: ${BUILD_LIST_FIELDS.join(", ")}. An unknown name is an error.`
+      },
+      meta: {
+        type: "boolean",
+        description: "Append a {total, filtered, returned, limit, offset} envelope so you can tell a truncated result from a complete one. Default false."
       }
     },
     required: []
@@ -23250,50 +23425,74 @@ var AD_CONFLICT_GATE_INSTRUCTION = "\n**AD conflict gate:** If this task conflic
 function hasReportFields(args) {
   return !!(args.completed || args.effort || args.estimated_effort || args.surprises || args.discovered_issues || args.architecture_notes);
 }
-async function handleBuildList(adapter2, config2) {
+async function handleBuildList(adapter2, config2, args = {}) {
+  const projection = resolveFields(args.fields, BUILD_LIST_FIELDS, "build_list");
+  if (!projection.ok) return errorResponse(projection.error);
+  const fields = projection.fields;
+  const emitMeta = wantsMeta(args.meta);
+  const rawLimit = args.limit;
+  const limit = typeof rawLimit === "number" && Number.isInteger(rawLimit) && rawLimit > 0 ? rawLimit : null;
+  const cap = (rows) => limit === null ? rows : rows.slice(0, limit);
   const result = await listBuilds(adapter2, config2);
   const warningPrefix = result.warnings.length > 0 ? result.warnings.map((w) => `> ${w}`).join("\n") + "\n\n" : "";
+  const emptyMeta = () => emitMeta ? { total: result.totalTasks, filtered: 0, returned: 0, limit, offset: 0 } : null;
   if (result.isEmpty) {
     if (result.currentCycle === 0) {
-      return textResponse(warningPrefix + `No tasks found \u2014 this looks like a new project. Run \`setup\` to initialise your project, then \`plan\` to create your first cycle.`);
+      return textResponse(withMeta(warningPrefix + `No tasks found \u2014 this looks like a new project. Run \`setup\` to initialise your project, then \`plan\` to create your first cycle.`, emptyMeta()));
     }
-    return textResponse(warningPrefix + `**Cycle ${result.currentCycle}** \u2014 Board is empty. Run \`plan\` to create your next cycle.`);
+    return textResponse(withMeta(warningPrefix + `**Cycle ${result.currentCycle}** \u2014 Board is empty. Run \`plan\` to create your next cycle.`, emptyMeta()));
   }
   if (result.noHandoffs) {
-    return textResponse(warningPrefix + `**Cycle ${result.currentCycle}** \u2014 No tasks with BUILD HANDOFFs. Run \`plan\` to generate your next cycle tasks.`);
+    return textResponse(withMeta(warningPrefix + `**Cycle ${result.currentCycle}** \u2014 No tasks with BUILD HANDOFFs. Run \`plan\` to generate your next cycle tasks.`, emptyMeta()));
   }
+  const inProgress = cap(result.inProgress);
+  const backlog = cap(result.backlog);
+  const blocked = cap(result.blocked);
   const lines = [];
   if (warningPrefix) {
     lines.push(warningPrefix.trimEnd(), "");
   }
   const totalCount = result.sorted.length + result.blocked.length;
   lines.push(`**Cycle ${result.currentCycle}** \u2014 ${totalCount} tasks with BUILD HANDOFFs:`, "");
-  if (result.inProgress.length > 0) {
-    lines.push(`## In Progress (${result.inProgress.length})`);
-    lines.push(...result.inProgress.map(formatListItem));
-    lines.push("");
-  }
-  if (result.backlog.length > 0) {
-    lines.push(`## Backlog (${result.backlog.length})`);
-    lines.push(...result.backlog.map(formatListItem));
-  }
-  if (result.blocked.length > 0) {
-    lines.push("", `## Blocked (${result.blocked.length}) \u2014 waiting on dependencies`);
-    for (const { task, unresolvedDeps } of result.blocked) {
-      lines.push(`- **${task.id}:** ${task.title}
+  if (fields) {
+    const columns = selectColumns(BUILD_LIST_COLUMNS, fields);
+    const rows = [...inProgress, ...backlog, ...blocked.map((b2) => b2.task)].map((t) => columns.map((c) => c.value(t)));
+    lines.push(renderTable(columns.map((c) => c.header), rows));
+  } else {
+    if (inProgress.length > 0) {
+      lines.push(`## In Progress (${result.inProgress.length})`);
+      lines.push(...inProgress.map(formatListItem));
+      lines.push("");
+    }
+    if (backlog.length > 0) {
+      lines.push(`## Backlog (${result.backlog.length})`);
+      lines.push(...backlog.map(formatListItem));
+    }
+    if (blocked.length > 0) {
+      lines.push("", `## Blocked (${result.blocked.length}) \u2014 waiting on dependencies`);
+      for (const { task, unresolvedDeps } of blocked) {
+        lines.push(`- **${task.id}:** ${task.title}
   Waiting on: ${unresolvedDeps.join(", ")}`);
+      }
     }
-  }
-  try {
-    const comments = await adapter2.getRecentTaskComments?.(30);
-    if (comments && comments.length > 0) {
-      const taskIds = new Set([...result.sorted, ...result.blocked.map((b2) => b2.task)].map((t) => t.id));
-      const section = formatTaskComments(comments, taskIds);
-      if (section) lines.push(section);
+    try {
+      const comments = await adapter2.getRecentTaskComments?.(30);
+      if (comments && comments.length > 0) {
+        const taskIds = new Set([...result.sorted, ...result.blocked.map((b2) => b2.task)].map((t) => t.id));
+        const section = formatTaskComments(comments, taskIds);
+        if (section) lines.push(section);
+      }
+    } catch {
     }
-  } catch {
   }
-  return textResponse(lines.join("\n"));
+  const meta = emitMeta ? {
+    total: result.totalTasks,
+    filtered: totalCount,
+    returned: inProgress.length + backlog.length + blocked.length,
+    limit,
+    offset: 0
+  } : null;
+  return textResponse(withMeta(lines.join("\n"), meta));
 }
 async function handleBuildDescribe(adapter2, args) {
   const taskId = args.task_id;
@@ -28706,7 +28905,7 @@ ${section}`;
     }
     tracker.mark("format-summary");
     const deepHint = deepHousekeeping ? "" : "\n\n*Tip: pass `full: true` for Research Signals + version-drift, or `deep_housekeeping: true` to also check orphaned branches, merged-but-In-Progress tasks, unrecorded commits, unregistered docs, and stale skill forks (implies `full`).*";
-    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName, carryForwardRefs) + unblockNote + deferredGateNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + onboardingCoachingNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection);
+    return { ...textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName, carryForwardRefs) + unblockNote + deferredGateNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + onboardingCoachingNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection), _cycleNumber: healthResult.cycleNumber };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const isKnownFriendly = /^(Orient failed|Project not found|No project|Setup required)/i.test(message);
@@ -29810,6 +30009,15 @@ function readLlmResponse(args) {
 }
 
 // src/tools/ad-view.ts
+var AD_COLUMNS = [
+  { name: "id", header: "AD", value: (d) => d.id },
+  { name: "title", header: "Title", value: (d) => d.title },
+  { name: "confidence", header: "Confidence", value: (d) => d.confidence },
+  { name: "superseded", header: "Superseded", value: (d) => d.superseded ? "yes" : "no" },
+  { name: "supersededBy", header: "Superseded By", value: (d) => d.supersededBy ?? "-" },
+  { name: "body", header: "Body", value: (d) => d.body.replace(/\s+/g, " ").trim() }
+];
+var AD_FIELDS = AD_COLUMNS.map((c) => c.name);
 var adViewTool = {
   name: "ad_view",
   description: "View one or all Active Decisions with full bodies. Use when you need to read the complete reasoning and evidence behind a specific AD before running strategy_change.",
@@ -29824,6 +30032,24 @@ var adViewTool = {
       include_superseded: {
         type: "boolean",
         description: "Include superseded (retired) ADs. Default false."
+      },
+      fields: {
+        type: "string",
+        description: `Optional sparse-field projection \u2014 comma-separated field names, e.g. "title,confidence". Returns a compact table of ONLY those fields (id is always included) instead of full AD bodies, which is far cheaper on session context when you just need the index. Allowed: ${AD_FIELDS.join(", ")}. An unknown name is an error.`
+      },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        description: "Max decisions to return. Omit to return all."
+      },
+      offset: {
+        type: "integer",
+        minimum: 0,
+        description: "Skip the first N decisions (pagination). Default 0."
+      },
+      meta: {
+        type: "boolean",
+        description: "Append a {total, filtered, returned, limit, offset} envelope so you can tell a truncated result from a complete one. Default false."
       }
     },
     required: []
@@ -29832,6 +30058,14 @@ var adViewTool = {
 async function handleAdView(adapter2, args) {
   const adId = args.ad_id;
   const includeSuperseded = args.include_superseded === true;
+  const projection = resolveFields(args.fields, AD_FIELDS, "ad_view");
+  if (!projection.ok) return errorResponse(projection.error);
+  const fields = projection.fields;
+  const emitMeta = wantsMeta(args.meta);
+  const rawLimit = args.limit;
+  const limit = typeof rawLimit === "number" && Number.isInteger(rawLimit) && rawLimit > 0 ? rawLimit : null;
+  const rawOffset = args.offset;
+  const offset = typeof rawOffset === "number" && Number.isInteger(rawOffset) && rawOffset > 0 ? rawOffset : 0;
   let decisions;
   try {
     decisions = await adapter2.getActiveDecisions({ includeRetired: includeSuperseded });
@@ -29844,26 +30078,39 @@ async function handleAdView(adapter2, args) {
       const ids = decisions.map((d) => d.id).join(", ");
       return errorResponse(`AD not found: ${adId}. Available: ${ids || "none"}`);
     }
+    const meta2 = emitMeta ? { total: decisions.length, filtered: 1, returned: 1, limit: null, offset: 0 } : null;
+    if (fields) {
+      const columns = selectColumns(AD_COLUMNS, fields);
+      const body = columns.map((c) => `- **${c.header}:** ${c.value(target)}`).join("\n");
+      return textResponse(withMeta(body, meta2));
+    }
     const supersededNote = target.superseded ? ` [SUPERSEDED by ${target.supersededBy}]` : "";
     return textResponse(
-      `## ${target.id}: ${target.title} [${target.confidence}]${supersededNote}
+      withMeta(`## ${target.id}: ${target.title} [${target.confidence}]${supersededNote}
 
-${target.body}`
+${target.body}`, meta2)
     );
   }
   const filtered = includeSuperseded ? decisions : decisions.filter((d) => !d.superseded);
-  if (filtered.length === 0) {
-    return textResponse("No active decisions found.");
+  const paged = limit === null && offset === 0 ? filtered : filtered.slice(offset, limit === null ? void 0 : offset + limit);
+  const meta = emitMeta ? { total: decisions.length, filtered: filtered.length, returned: paged.length, limit, offset } : null;
+  if (paged.length === 0) {
+    return textResponse(withMeta("No active decisions found.", meta));
   }
-  const formatted = filtered.map((d) => {
+  if (fields) {
+    const columns = selectColumns(AD_COLUMNS, fields);
+    const rows = paged.map((d) => columns.map((c) => c.value(d)));
+    return textResponse(withMeta(renderTable(columns.map((c) => c.header), rows), meta));
+  }
+  const formatted = paged.map((d) => {
     const supersededNote = d.superseded ? ` [SUPERSEDED by ${d.supersededBy}]` : "";
     return `## ${d.id}: ${d.title} [${d.confidence}]${supersededNote}
 
 ${d.body}`;
   }).join("\n\n---\n\n");
-  return textResponse(`# Active Decisions (${filtered.length})
+  return textResponse(withMeta(`# Active Decisions (${paged.length})
 
-${formatted}`);
+${formatted}`, meta));
 }
 
 // src/tools/learning-action.ts
@@ -31160,7 +31407,7 @@ function createServer(adapter2, config2) {
         case "setup":
           return handleSetup(adapter2, config2, safeArgs, server2.getClientVersion()?.name);
         case "build_list":
-          return handleBuildList(adapter2, config2);
+          return handleBuildList(adapter2, config2, safeArgs);
         case "build_describe":
           return handleBuildDescribe(adapter2, safeArgs);
         case "build_execute":
@@ -31289,9 +31536,17 @@ ${usageLine(decision.usage)}`;
     const usage = result._usage;
     const contextBytes = result._contextBytes;
     const contextUtilisation = result._contextUtilisation;
+    const toolCycleNumber = result._cycleNumber;
     delete result._usage;
     delete result._contextBytes;
     delete result._contextUtilisation;
+    delete result._cycleNumber;
+    recordToolRun(adapter2, {
+      toolName: name,
+      contextBytes: measureResultBytes(result.content),
+      durationMs: elapsed,
+      cycleNumber: toolCycleNumber ?? null
+    });
     const isError = result.content.some((c) => c.text.startsWith("Error:") || c.text.startsWith("\u274C"));
     recordToolOutcome(!isError, callerKey);
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.71",
+  "version": "0.7.73",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "mcpName": "io.github.getpapi/papi",