@rubytech/create-realagent-code 0.1.614 → 0.1.616

package/payload/premium-plugins/real-agent/plugins/loop/mcp/src/lib/loop-api.ts

@@ -1,4 +1,11 @@
 import { selectLoopKeyStore } from "./key-store.js";
+import { LOOP_SCHEMA_KEYS } from "./loop-schema-keys.js";
+import {
+  censusRecords,
+  falsyPresentKeys,
+  matchPathPattern,
+  wireKeys,
+} from "./field-census.js";
 
 // ─────────────────────────────────────────────────────────────────
 // Loop API V2 HTTP Client + Cross-Team Aggregation Engine
@@ -17,6 +24,12 @@ import { selectLoopKeyStore } from "./key-store.js";
 // ─────────────────────────────────────────────────────────────────
 
 const LOOP_BASE_URL = "https://api.loop.software";
+
+// The Loop API version every path below targets. Declared once so tool output
+// and log lines can both state which version a read actually reached. An agent
+// reading either must never have to infer it from the shape of the paths: a
+// capability audit did exactly that on 2026-08-18 and recorded v1.
+export const LOOP_API_VERSION = "v2";
 const REQUEST_TIMEOUT_MS = 10_000;
 const TIMEOUT_RETRY_BACKOFF_MS = 2_000;
 const DEFAULT_LIMIT_PER_TEAM = 50;
@@ -139,14 +152,58 @@ function logErrorBody(
   );
 }
 
-/**
- * Make a GET request to the Loop API V2.
- */
+// Two standing signals, both blind spots before this.
+//
+// field-census: a read that returned falsy-present keys while raw was off gave
+// its caller a lossy answer. It fires on every read whether or not raw was
+// asked for, because "nobody asked for raw" is exactly the failure being
+// watched and it produces no event of its own. A log hung on the raw path
+// would only ever record the reads that were already correct.
+//
+// schema-drift: Loop's own deploys change what arrives, which never reproduces
+// on demand here. schemaOnly means Loop stopped sending documented fields;
+// wireOnly means Loop added fields we have never seen. An unmatched path says
+// so rather than skipping silently.
+function emitReadSignals(toolName: string, path: string, data: unknown, raw: boolean): void {
+  const records = censusRecords(data);
+  const keys = wireKeys(data);
+  const falsy = falsyPresentKeys(data);
+  // falsyKeys unions across records, so it alone cannot separate one lossy row
+  // in two hundred from all two hundred. falsyRecords counts the rows carrying
+  // at least one, which is the difference between an edge case and a systemic
+  // gap in the operator's data.
+  const falsyRecords = records.filter((r) => falsyPresentKeys(r).length > 0).length;
+
+  console.error(
+    `[loop] op=field-census tool=${toolName} apiVersion=${LOOP_API_VERSION} ` +
+    `raw=${raw} records=${records.length} falsyRecords=${falsyRecords} ` +
+    `wireKeys=${keys.length} falsyKeys=${falsy.length ? falsy.join(",") : "-"}`
+  );
+
+  const patterns = Object.keys(LOOP_SCHEMA_KEYS);
+  const pattern = matchPathPattern(path, patterns);
+  if (!pattern) {
+    console.error(
+      `[loop] op=schema-drift tool=${toolName} apiVersion=${LOOP_API_VERSION} path=unmatched`
+    );
+    return;
+  }
+  const documented = LOOP_SCHEMA_KEYS[pattern];
+  const schemaOnly = documented.filter((k) => !keys.includes(k));
+  const wireOnly = keys.filter((k) => !documented.includes(k));
+  console.error(
+    `[loop] op=schema-drift tool=${toolName} apiVersion=${LOOP_API_VERSION} path=${pattern} ` +
+    `schemaOnly=${schemaOnly.length ? schemaOnly.join(",") : "-"} ` +
+    `wireOnly=${wireOnly.length ? wireOnly.join(",") : "-"}`
+  );
+}
+
 export async function loopGet<T>(
   apiKey: string,
   path: string,
   toolName: string,
-  teamName: string
+  teamName: string,
+  opts: { raw?: boolean } = {}
 ): Promise<T> {
   const url = `${LOOP_BASE_URL}${path}`;
   const start = Date.now();
@@ -158,7 +215,8 @@ export async function loopGet<T>(
 
   const duration = Date.now() - start;
   console.error(
-    `[loop] ${toolName} team=${teamName} endpoint=GET ${path} status=${response.status} duration=${duration}ms`
+    `[loop] op=request tool=${toolName} apiVersion=${LOOP_API_VERSION} team=${teamName} ` +
+    `method=GET path=${path} status=${response.status} duration=${duration}ms`
   );
 
   if (response.status === 204) {
@@ -172,9 +230,10 @@ export async function loopGet<T>(
   }
 
   const text = await response.text();
+  let data: T;
   try {
     const parsed = JSON.parse(text);
-    return unwrapEnvelope<T>(parsed, toolName, teamName);
+    data = unwrapEnvelope<T>(parsed, toolName, teamName);
   } catch (err) {
     if (err instanceof SyntaxError) {
       throw new Error(
@@ -184,6 +243,13 @@ export async function loopGet<T>(
     }
     throw err;
   }
+
+  // Outside the parse guard on purpose. Inside it, any throw from
+  // instrumentation was caught by a handler written for parse failures and
+  // re-thrown, which drops the whole team from the aggregate and blames Loop
+  // for a telemetry bug. Observability must never fail the read it observes.
+  emitReadSignals(toolName, path, data, opts.raw === true);
+  return data;
 }
 
 /**
@@ -214,7 +280,8 @@ export async function loopPost<T>(
 
   const duration = Date.now() - start;
   console.error(
-    `[loop] WRITE ${toolName} team=${teamName} endpoint=POST ${path} status=${response.status} duration=${duration}ms`
+    `[loop] op=request kind=write tool=${toolName} apiVersion=${LOOP_API_VERSION} team=${teamName} ` +
+    `method=POST path=${path} status=${response.status} duration=${duration}ms`
   );
 
   if (response.status === 204) {
@@ -269,7 +336,8 @@ export async function loopPut<T>(
 
   const duration = Date.now() - start;
   console.error(
-    `[loop] WRITE ${toolName} team=${teamName} endpoint=PUT ${path} status=${response.status} duration=${duration}ms`
+    `[loop] op=request kind=write tool=${toolName} apiVersion=${LOOP_API_VERSION} team=${teamName} ` +
+    `method=PUT path=${path} status=${response.status} duration=${duration}ms`
   );
 
   if (response.status === 204) {
@@ -435,11 +503,11 @@ export async function aggregateAcrossTeams<T>(
   const erroredCount = failures.length - timedOutCount;
 
   console.error(
-    `[loop] aggregate tool=${toolName} teams=${keys.length} ` +
+    `[loop] aggregate tool=${toolName} apiVersion=${LOOP_API_VERSION} teams=${keys.length} ` +
     `succeeded=${results.length} failed=${failures.length} skipped=${skipped.length}`
   );
   console.error(
-    `[loop] aggregate-coverage tool=${toolName} requested=${keys.length} ` +
+    `[loop] aggregate-coverage tool=${toolName} apiVersion=${LOOP_API_VERSION} requested=${keys.length} ` +
     `answered=${results.length} timed_out=${timedOutCount} errored=${erroredCount}`
   );
 
@@ -482,13 +550,37 @@ export async function withTeamKey<T>(
 /**
  * Format an aggregation result into a human-readable text response.
  */
+/**
+ * Version header and raw rendering for the reads that do NOT aggregate across
+ * teams. `withTeamKey` tools format their own prose, so without this they were
+ * the four Loop reads that named no version and offered no way to see the
+ * field set — the exact defect this module exists to close, surviving in the
+ * corner the aggregation path does not cover.
+ */
+export function formatSingleTeamRead(
+  data: unknown,
+  prose: string,
+  opts: { raw?: boolean } = {}
+): string {
+  const version = `Loop API ${LOOP_API_VERSION}`;
+  if (opts.raw === true) {
+    return `[${version}]\n\`\`\`json\n${JSON.stringify(data, null, 2)}\n\`\`\``;
+  }
+  return `[${version}] ${prose}`;
+}
+
 export function formatAggregationResult<T>(
   result: AggregationResult<T>,
   formatItem: (item: T, teamName: string) => string,
-  entityName: string
+  entityName: string,
+  opts: { raw?: boolean } = {}
 ): string {
+  // Every branch states the version the read reached. An agent must be able to
+  // answer "which version did I just read" from the output alone.
+  const version = `Loop API ${LOOP_API_VERSION}`;
+
   if (result.totalTeams === 0) {
-    return "No Loop teams registered. Use loop-key-register to add team API keys.";
+    return `[${version}] No Loop teams registered. Use loop-key-register to add team API keys.`;
   }
 
   const allSkippedOrFailed =
@@ -499,7 +591,7 @@ export function formatAggregationResult<T>(
       ...result.failures.map((f) => `${f.teamName}: ${f.reason}`),
       ...result.skipped.map((s) => `${s.teamName}: ${s.reason}`),
     ];
-    return `All teams failed or were skipped:\n${reasons.join("\n")}`;
+    return `[${version}] All teams failed or were skipped:\n${reasons.join("\n")}`;
   }
 
   const lines: string[] = [];
@@ -510,7 +602,14 @@ export function formatAggregationResult<T>(
     totalItems += teamResult.data.length;
     lines.push(`\n## ${teamResult.teamName}`);
     for (const item of teamResult.data) {
-      lines.push(formatItem(item, teamResult.teamName));
+      // Raw serialises the wire payload, not the interface, so a field no tool
+      // declares still appears — and 0, false and "" survive, which is the
+      // whole point: prose drops them and makes a zero look like an absence.
+      lines.push(
+        opts.raw === true
+          ? "```json\n" + JSON.stringify(item, null, 2) + "\n```"
+          : formatItem(item, teamResult.teamName)
+      );
     }
   }
 
@@ -523,18 +622,18 @@ export function formatAggregationResult<T>(
 
   if (totalItems === 0) {
     if (failed > 0) {
-      return `No ${entityName} found across ${answered} of ${totalCovered} teams (${coverageNote}).`;
+      return `[${version}] No ${entityName} found across ${answered} of ${totalCovered} teams (${coverageNote}).`;
     }
     const teamCount =
       result.results.length === 1
         ? result.results[0].teamName
         : `${result.results.length} teams`;
-    return `No ${entityName} found across ${teamCount}.`;
+    return `[${version}] No ${entityName} found across ${teamCount}.`;
   }
 
   const teamCountFragment =
     failed > 0 ? `${answered} of ${totalCovered} team(s)` : `${answered} team(s)`;
-  let header = `${totalItems} ${entityName} across ${teamCountFragment}:`;
+  let header = `[${version}] ${totalItems} ${entityName} across ${teamCountFragment}:`;
   const parts: string[] = [header, ...lines];
 
   if (failed > 0) {