pi-usereq 0.5.0 → 0.6.0

package/src/core/find-payload.ts

@@ -156,10 +156,11 @@ export interface FindToolRequestSection {
 
 /**
  * @brief Describes the summary section of the find payload.
- * @details Exposes aggregate file, match, line, and Doxygen counts as numeric fields plus one stable search-status discriminator. The interface is compile-time only and introduces no runtime cost.
+ * @details Exposes aggregate file, match, line, and Doxygen counts as numeric fields plus one stable search-status discriminator and the normalized validation error when request parsing fails. The interface is compile-time only and introduces no runtime cost.
  */
 export interface FindToolSummarySection {
   search_status: FindSearchStatus;
+  validation_error_message?: string;
   processable_file_count: number;
   matched_file_count: number;
   no_match_file_count: number;
@@ -172,22 +173,20 @@ export interface FindToolSummarySection {
 
 /**
  * @brief Describes the repository section of the find payload.
- * @details Stores the base path, configured source-directory scope, canonical file list, and supported-tag matrix needed to specialize later searches without rereading tool descriptions. The interface is compile-time only and introduces no runtime cost.
+ * @details Stores the base path, configured source-directory scope, and canonical file list used during search while omitting the static supported-tag matrix because that data belongs in tool registration metadata. The interface is compile-time only and introduces no runtime cost.
  */
 export interface FindToolRepositorySection {
   root_directory_path: string;
   source_directory_paths: string[];
   file_count: number;
   file_canonical_paths: string[];
-  supported_tags_by_language: Record<string, string[]>;
 }
 
 /**
  * @brief Describes the full agent-oriented find payload.
- * @details Orders the top-level sections as request, summary, repository, and files so execution metadata can be appended deterministically by the tool wrapper. The interface is compile-time only and introduces no runtime cost.
+ * @details Exposes only aggregate search totals, repository scope, and per-file match records, omitting request echoes and static supported-tag matrices that already belong in registration metadata. The interface is compile-time only and introduces no runtime cost.
  */
 export interface FindToolPayload {
-  request: FindToolRequestSection;
   summary: FindToolSummarySection;
   repository: FindToolRepositorySection;
   files: FindToolFileEntry[];
@@ -262,19 +261,6 @@ function buildLineRange(startLineNumber: number, endLineNumber: number): FindLin
   };
 }
 
-/**
- * @brief Returns the supported-tag matrix ordered for deterministic JSON emission.
- * @details Sorts languages alphabetically and tag arrays lexicographically so downstream agents can reuse the matrix without reparsing human prose. Runtime is O(l * t log t). No side effects occur.
- * @return {Record<string, string[]>} Supported tags keyed by canonical language identifier.
- */
-function buildSupportedTagsByLanguage(): Record<string, string[]> {
-  return Object.fromEntries(
-    Object.entries(LANGUAGE_TAGS)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([language, tagSet]) => [language, [...tagSet].sort()]),
-  );
-}
-
 /**
  * @brief Resolves one stable symbol name from an analyzed element.
  * @details Prefers explicit analyzer name metadata, then falls back to the derived signature or the first source line so every matched construct retains a direct-access identifier. Runtime is O(1). No side effects occur.
@@ -717,9 +703,9 @@ function analyzeFindFile(
 
 /**
  * @brief Builds the full agent-oriented find payload.
- * @details Validates request parameters, analyzes requested files in caller order when the request is valid, preserves skipped and no-match outcomes in structured file entries, computes aggregate numeric totals, and emits a structured supported-tag matrix. Runtime is O(F log F + S + M). Side effects are limited to filesystem reads and optional stderr logging.
+ * @details Validates request parameters, analyzes requested files in caller order when the request is valid, preserves skipped and no-match outcomes in structured file entries, computes aggregate numeric totals, and omits request echoes plus the static supported-tag matrix already encoded in registration metadata. Runtime is O(F log F + S + M). Side effects are limited to filesystem reads and optional stderr logging.
  * @param[in] options {BuildFindToolPayloadOptions} Payload-construction options.
- * @return {FindToolPayload} Structured find payload ordered as request, summary, repository, and files.
+ * @return {FindToolPayload} Structured find payload ordered as summary, repository, and files.
  * @satisfies REQ-089, REQ-090, REQ-091, REQ-092, REQ-093, REQ-094, REQ-096, REQ-098
  */
 export function buildFindToolPayload(options: BuildFindToolPayloadOptions): FindToolPayload {
@@ -835,28 +821,20 @@ export function buildFindToolPayload(options: BuildFindToolPayloadOptions): Find
   const processableFiles = files.filter((file) => file.status !== "skipped");
   const repositoryFileCanonicalPaths = files.map((file) => file.canonical_path);
 
+  void toolName;
+  void scope;
+  void lineNumberMode;
+  void tagFilter;
+  void pattern;
+  void canonicalRequestedPaths;
   return {
-    request: {
-      tool_name: toolName,
-      scope,
-      base_dir_path: absoluteBaseDir,
-      line_number_mode: lineNumberMode,
-      tag_filter_text: tagFilter,
-      tag_filter_values: tagValidation.tagValues,
-      tag_filter_status: tagValidation.status,
-      tag_filter_error_message: tagValidation.errorMessage,
-      name_regex_text: pattern,
-      regex_engine: "javascript-regexp-search",
-      regex_status: regexValidation.status,
-      regex_error_message: regexValidation.errorMessage,
-      source_directory_count: sourceDirectoryPaths.length,
-      source_directory_paths: sourceDirectoryPaths.map((sourceDirectoryPath) => canonicalizeFindPath(sourceDirectoryPath, absoluteBaseDir)),
-      requested_file_count: requestedPaths.length,
-      requested_input_paths: [...requestedPaths],
-      requested_canonical_paths: canonicalRequestedPaths,
-    },
     summary: {
       search_status: searchStatus,
+      validation_error_message: tagValidation.status === "invalid"
+        ? tagValidation.errorMessage
+        : regexValidation.status === "invalid"
+          ? regexValidation.errorMessage
+          : undefined,
       processable_file_count: processableFiles.length,
       matched_file_count: matchedFiles.length,
       no_match_file_count: files.filter((file) => file.status === "no_match").length,
@@ -874,7 +852,6 @@ export function buildFindToolPayload(options: BuildFindToolPayloadOptions): Find
       source_directory_paths: sourceDirectoryPaths.map((sourceDirectoryPath) => canonicalizeFindPath(sourceDirectoryPath, absoluteBaseDir)),
       file_count: repositoryFileCanonicalPaths.length,
       file_canonical_paths: repositoryFileCanonicalPaths,
-      supported_tags_by_language: buildSupportedTagsByLanguage(),
     },
     files,
   };
@@ -889,11 +866,11 @@ export function buildFindToolPayload(options: BuildFindToolPayloadOptions): Find
  */
 export function buildFindToolExecutionStderr(payload: FindToolPayload): string {
   const diagnostics: string[] = [];
-  if (payload.request.tag_filter_status === "invalid") {
-    diagnostics.push(`error: tag_filter: ${payload.request.tag_filter_error_message ?? "invalid tag filter"}`);
+  if (payload.summary.search_status === "invalid_tag_filter") {
+    diagnostics.push(`error: tag_filter: ${payload.summary.validation_error_message ?? "invalid tag filter"}`);
   }
-  if (payload.request.regex_status === "invalid") {
-    diagnostics.push(`error: name_regex: ${payload.request.regex_error_message ?? "invalid regex"}`);
+  if (payload.summary.search_status === "invalid_regex") {
+    diagnostics.push(`error: name_regex: ${payload.summary.validation_error_message ?? "invalid regex"}`);
   }
   payload.files.forEach((file) => {
     if (file.status === "skipped") {

package/src/core/reference-payload.ts

@@ -182,10 +182,9 @@ export interface ReferenceToolRepositorySection {
 
 /**
  * @brief Describes the full agent-oriented references payload.
- * @details Orders the top-level sections as request, summary, repository, and files for deterministic downstream traversal. The interface is compile-time only and introduces no runtime cost.
+ * @details Exposes only aggregate analysis totals, repository structure, and per-file reference records, omitting request echoes that are already known to the caller or encoded in the tool registration. The interface is compile-time only and introduces no runtime cost.
  */
 export interface ReferenceToolPayload {
-  request: ReferenceToolRequestSection;
   summary: ReferenceToolSummarySection;
   repository: ReferenceToolRepositorySection;
   files: ReferenceToolFileEntry[];
@@ -663,9 +662,9 @@ function analyzeReferenceFile(
 
 /**
  * @brief Builds the full agent-oriented references payload.
- * @details Validates requested paths against the filesystem, analyzes processable files in caller order, preserves skipped and failed inputs in structured file entries, computes aggregate numeric totals, and emits a structured repository tree. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
+ * @details Validates requested paths against the filesystem, analyzes processable files in caller order, preserves skipped and failed inputs in structured file entries, computes aggregate numeric totals, and emits structured repository data without echoing request metadata already known to the caller. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
  * @param[in] options {BuildReferenceToolPayloadOptions} Payload-construction options.
- * @return {ReferenceToolPayload} Structured references payload ordered as request, summary, repository, and files.
+ * @return {ReferenceToolPayload} Structured references payload ordered as summary, repository, and files.
  * @satisfies REQ-011, REQ-014, REQ-076, REQ-077, REQ-078, REQ-079
  */
 export function buildReferenceToolPayload(options: BuildReferenceToolPayloadOptions): ReferenceToolPayload {
@@ -761,17 +760,10 @@ export function buildReferenceToolPayload(options: BuildReferenceToolPayloadOpti
   const repositoryFileCanonicalPaths = [...new Set(analyzedFiles.map((file) => file.canonical_path))]
     .sort((left, right) => left.localeCompare(right));
 
+  void toolName;
+  void scope;
+  void canonicalRequestedPaths;
   return {
-    request: {
-      tool_name: toolName,
-      scope,
-      base_dir_path: absoluteBaseDir,
-      source_directory_count: sourceDirectoryPaths.length,
-      source_directory_paths: sourceDirectoryPaths.map((sourceDirectoryPath) => canonicalizeReferencePath(sourceDirectoryPath, absoluteBaseDir)),
-      requested_file_count: requestedPaths.length,
-      requested_input_paths: [...requestedPaths],
-      requested_canonical_paths: canonicalRequestedPaths,
-    },
     summary: {
       processable_file_count: processableFiles.length,
       analyzed_file_count: analyzedFiles.length,

package/src/core/token-counter.ts

@@ -175,13 +175,11 @@ export interface TokenToolGuidanceSection {
 
 /**
  * @brief Describes the full agent-oriented token payload.
- * @details Orders the top-level sections as request, summary, files, and guidance for deterministic downstream traversal. The interface is compile-time only and introduces no runtime cost.
+ * @details Exposes only aggregate numeric totals plus per-file metrics, omitting request echoes and derived guidance that can be inferred from tool registration or recomputed by the caller. The interface is compile-time only and introduces no runtime cost.
  */
 export interface TokenToolPayload {
-  request: TokenToolRequestSection;
   summary: TokenToolSummarySection;
   files: TokenToolFileEntry[];
-  guidance: TokenToolGuidanceSection;
 }
 
 /**
@@ -359,41 +357,6 @@ function roundRatio(numerator: number, denominator: number): number {
   return Number((numerator / denominator).toFixed(6));
 }
 
-/**
- * @brief Orders canonical file paths by one numeric metric while removing duplicates.
- * @details Filters to counted file entries, sorts by the supplied metric direction, breaks ties by canonical path, and preserves only the first occurrence of each path. Runtime is O(n log n). No external state is mutated.
- * @param[in] files {TokenToolFileEntry[]} Token payload file entries.
- * @param[in] metric {(entry: TokenToolFileEntry) => number} Numeric metric selector.
- * @param[in] direction {"asc" | "desc"} Sort direction.
- * @return {string[]} Unique canonical paths ordered by the requested metric.
- */
-function orderPathsByMetric(
-  files: TokenToolFileEntry[],
-  metric: (entry: TokenToolFileEntry) => number,
-  direction: "asc" | "desc",
-): string[] {
-  const sorted = files
-    .filter((entry) => entry.status === "counted")
-    .sort((left, right) => {
-      const leftMetric = metric(left);
-      const rightMetric = metric(right);
-      if (leftMetric === rightMetric) {
-        return left.canonical_path.localeCompare(right.canonical_path);
-      }
-      return direction === "desc" ? rightMetric - leftMetric : leftMetric - rightMetric;
-    });
-  const seen = new Set<string>();
-  const orderedPaths: string[] = [];
-  for (const entry of sorted) {
-    if (seen.has(entry.canonical_path)) {
-      continue;
-    }
-    seen.add(entry.canonical_path);
-    orderedPaths.push(entry.canonical_path);
-  }
-  return orderedPaths;
-}
-
 /**
  * @brief Probes one requested path before token counting.
  * @details Resolves whether the target exists and is a regular file while capturing a stable skip reason for missing or non-file inputs. Runtime is dominated by one filesystem stat. Side effects are limited to filesystem reads.
@@ -496,9 +459,9 @@ export function countFilesMetrics(filePaths: string[], encodingName = TOKEN_COUN
 
 /**
  * @brief Builds the agent-oriented JSON payload for token-centric tools.
- * @details Validates requested paths against the filesystem, counts token metrics for processable files, preserves caller order in the file table, separates raw observations from derived guidance, and emits direct-access file facts such as line ranges, sizes, headings, and optional Doxygen file fields. Runtime is O(F log F + S). Side effects are limited to filesystem reads.
+ * @details Validates requested paths against the filesystem, counts token metrics for processable files, preserves caller order in the file table, and emits direct-access file facts such as sizes, headings, and optional Doxygen file fields while omitting request echoes and derived guidance. Runtime is O(F + S). Side effects are limited to filesystem reads.
  * @param[in] options {BuildTokenToolPayloadOptions} Payload-construction options.
- * @return {TokenToolPayload} Structured token payload ordered as request, summary, files, guidance.
+ * @return {TokenToolPayload} Structured token payload ordered as summary then files.
  * @satisfies REQ-010, REQ-017, REQ-069, REQ-070, REQ-071, REQ-073, REQ-074, REQ-075
  */
 export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): TokenToolPayload {
@@ -596,71 +559,7 @@ export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): To
   const countedFileCount = filesWithShares.filter((entry) => entry.status === "counted").length;
   const errorFileCount = filesWithShares.filter((entry) => entry.status === "error").length;
   const skippedFileCount = filesWithShares.filter((entry) => entry.status === "skipped").length;
-  const countedPathsByTokenCountDesc = orderPathsByMetric(filesWithShares, (entry) => entry.token_count, "desc");
-  const countedPathsByTokenCountAsc = orderPathsByMetric(filesWithShares, (entry) => entry.token_count, "asc");
-  const countedPathsByLineCountDesc = orderPathsByMetric(filesWithShares, (entry) => entry.line_count, "desc");
-  const dominantTokenFileEntry = filesWithShares
-    .filter((entry) => entry.status === "counted")
-    .sort((left, right) => {
-      if (left.token_count === right.token_count) {
-        return left.canonical_path.localeCompare(right.canonical_path);
-      }
-      return right.token_count - left.token_count;
-    })[0];
-  const skippedInputs = filesWithShares
-    .filter((entry) => entry.status === "skipped" && entry.error_message)
-    .map((entry) => ({
-      input_path: entry.input_path,
-      canonical_path: entry.canonical_path,
-      reason: entry.error_message!,
-    }));
-  const errorInputs = filesWithShares
-    .filter((entry) => entry.status === "error" && entry.error_message)
-    .map((entry) => ({
-      input_path: entry.input_path,
-      canonical_path: entry.canonical_path,
-      reason: entry.error_message!,
-    }));
-  const derivedRecommendations: TokenToolRecommendation[] = countedPathsByTokenCountDesc.length > 0
-    ? [
-      {
-        kind: "prioritize_high_token_paths",
-        basis_metric_name: "token_count",
-        ordered_paths: countedPathsByTokenCountDesc,
-      },
-      {
-        kind: "defer_low_token_paths",
-        basis_metric_name: "token_count",
-        ordered_paths: countedPathsByTokenCountAsc,
-      },
-    ]
-    : [];
-  const actionableNextSteps: TokenToolNextStepHint[] = countedPathsByTokenCountDesc.length > 0
-    ? [
-      {
-        kind: "read_top_token_paths_first",
-        ordered_paths: countedPathsByTokenCountDesc.slice(0, 3),
-        goal: "minimize context-truncation risk during initial review",
-      },
-      {
-        kind: "reserve_low_token_paths_for_follow_up",
-        ordered_paths: countedPathsByTokenCountAsc.slice(0, 3),
-        goal: "defer lower-cost files until high-cost files have been reviewed",
-      },
-    ]
-    : [];
   return {
-    request: {
-      tool_name: options.toolName,
-      scope: options.scope,
-      encoding_name: encodingName,
-      base_dir_path: baseDir.split(path.sep).join("/"),
-      requested_file_count: options.requestedPaths.length,
-      requested_input_paths: options.requestedPaths,
-      requested_canonical_paths: requestedEntries.map((entry) => entry.canonicalPath),
-      docs_dir_path: options.docsDir,
-      canonical_doc_names: options.canonicalDocNames,
-    },
     summary: {
       processable_file_count: countedFileCount + errorFileCount,
       counted_file_count: countedFileCount,
@@ -676,23 +575,6 @@ export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): To
       average_line_count_per_counted_file: countedFileCount === 0 ? 0 : Number((totalLineCount / countedFileCount).toFixed(6)),
     },
     files: filesWithShares,
-    guidance: {
-      source_observations: {
-        counted_paths_by_token_count_desc: countedPathsByTokenCountDesc,
-        counted_paths_by_line_count_desc: countedPathsByLineCountDesc,
-        skipped_inputs: skippedInputs,
-        error_inputs: errorInputs,
-        dominant_token_file: dominantTokenFileEntry
-          ? {
-            canonical_path: dominantTokenFileEntry.canonical_path,
-            token_count: dominantTokenFileEntry.token_count,
-            token_share: dominantTokenFileEntry.token_share,
-          }
-          : undefined,
-      },
-      derived_recommendations: derivedRecommendations,
-      actionable_next_steps: actionableNextSteps,
-    },
   };
 }