@tyvm/knowhow 0.0.159 → 0.0.160

package/src/processors/tools/grepToolResponse.ts

@@ -1,230 +0,0 @@
-import { Tool } from "../../clients";
-
-export interface GrepOptions {
-  ignoreCase?: boolean;
-  invertMatch?: boolean;
-  contextBefore?: number;
-  contextAfter?: number;
-  maxResults?: number;
-  resultOffset?: number;
-  maxCharacters?: number;
-  lineCharacterOffset?: number;
-  maxLineCharacters?: number;
-}
-
-const DEFAULT_MAX_RESULTS = 100;
-const MAX_RESULTS = 1000;
-const DEFAULT_MAX_CHARACTERS = 20_000;
-const MAX_CHARACTERS = 50_000;
-const DEFAULT_MAX_LINE_CHARACTERS = 4_000;
-const MAX_LINE_CHARACTERS = 10_000;
-const FOOTER_RESERVE = 700;
-
-function boundedInteger(
-  value: number | undefined,
-  fallback: number,
-  min: number,
-  max: number
-): number {
-  return Math.min(
-    max,
-    Math.max(min, Number.isFinite(value) ? Math.floor(value as number) : fallback)
-  );
-}
-
-/** Search stored tool-response text without ever returning an unbounded result. */
-export async function executeGrep(
-  data: string,
-  toolCallId: string,
-  pattern: string,
-  availableIds: string[],
-  options?: GrepOptions,
-  toolNameMap?: { [toolCallId: string]: string }
-): Promise<string> {
-  if (!data) {
-    const idList = availableIds
-      .map((id) => {
-        const name = toolNameMap?.[id];
-        return name ? `${id} (${name})` : id;
-      })
-      .join("\n  - ");
-    const maxCharacters = boundedInteger(
-      options?.maxCharacters,
-      DEFAULT_MAX_CHARACTERS,
-      1000,
-      MAX_CHARACTERS
-    );
-    return `Error: No tool response found for toolCallId "${toolCallId}". Call listStoredToolResponses to see all available responses with their tool names.\n\nAvailable toolCallIds:\n  - ${idList || "(none)"}`.slice(
-      0,
-      maxCharacters
-    );
-  }
-
-  try {
-    const lines = data.split("\n");
-    const matchedResults: string[] = [];
-    const ignoreCase = options?.ignoreCase ?? false;
-    const invertMatch = options?.invertMatch ?? false;
-    const contextBefore = boundedInteger(options?.contextBefore, 0, 0, 1000);
-    const contextAfter = boundedInteger(options?.contextAfter, 0, 0, 1000);
-    const maxResults = boundedInteger(options?.maxResults, DEFAULT_MAX_RESULTS, 1, MAX_RESULTS);
-    const resultOffset = boundedInteger(options?.resultOffset, 0, 0, Number.MAX_SAFE_INTEGER);
-    const maxCharacters = boundedInteger(
-      options?.maxCharacters,
-      DEFAULT_MAX_CHARACTERS,
-      1000,
-      MAX_CHARACTERS
-    );
-    const lineCharacterOffset = boundedInteger(
-      options?.lineCharacterOffset,
-      0,
-      0,
-      Number.MAX_SAFE_INTEGER
-    );
-    const maxLineCharacters = boundedInteger(
-      options?.maxLineCharacters,
-      DEFAULT_MAX_LINE_CHARACTERS,
-      100,
-      MAX_LINE_CHARACTERS
-    );
-    const contentBudget = Math.max(1, maxCharacters - FOOTER_RESERVE);
-    const regex = new RegExp(pattern, ignoreCase ? "i" : "");
-
-    let totalMatches = 0;
-    let outputCharacters = 0;
-    let outputTruncated = false;
-    const pagedLineNumbers = new Set<number>();
-
-    for (let i = 0; i < lines.length; i++) {
-      const matches = regex.test(lines[i]);
-      if (invertMatch ? matches : !matches) continue;
-
-      const resultIndex = totalMatches++;
-      const startIdx = Math.max(0, i - contextBefore);
-      const endIdx = Math.min(lines.length - 1, i + contextAfter);
-
-      if (
-        resultIndex >= resultOffset &&
-        matchedResults.length < maxResults &&
-        !outputTruncated
-      ) {
-        const contextLines: string[] = [];
-        for (let j = startIdx; j <= endIdx; j++) {
-          const sourceLine = lines[j];
-          const visibleLine = sourceLine.slice(
-            lineCharacterOffset,
-            lineCharacterOffset + maxLineCharacters
-          );
-          const prefix = j === i ? "> " : "  ";
-          let rendered = `${prefix}${j + 1}: ${visibleLine}`;
-
-          if (lineCharacterOffset >= sourceLine.length && sourceLine.length > 0) {
-            rendered += ` [no characters at offset ${lineCharacterOffset}; line length=${sourceLine.length}]`;
-          } else if (lineCharacterOffset + maxLineCharacters < sourceLine.length) {
-            pagedLineNumbers.add(j + 1);
-            rendered += `\n  [line ${j + 1} truncated; characters ${lineCharacterOffset}-${lineCharacterOffset + visibleLine.length - 1} of ${sourceLine.length}]`;
-          }
-          contextLines.push(rendered);
-        }
-
-        const separatorLength = matchedResults.length > 0 ? 5 : 0;
-        const result = contextLines.join("\n");
-        const remaining = contentBudget - outputCharacters - separatorLength;
-        if (result.length > remaining) {
-          if (matchedResults.length === 0 && remaining > 80) {
-            matchedResults.push(
-              `${result.slice(0, remaining - 48)}\n[result page truncated by maxCharacters]`
-            );
-            outputCharacters = contentBudget;
-          }
-          outputTruncated = true;
-        } else {
-          matchedResults.push(result);
-          outputCharacters += separatorLength + result.length;
-        }
-      }
-
-      // Avoid duplicate result blocks when their after-context overlaps a match.
-      i += contextAfter;
-    }
-
-    if (totalMatches === 0) {
-      const preview = pattern.length > 200 ? `${pattern.slice(0, 200)}…` : pattern;
-      return `No matches found for pattern "${preview}" in toolCallId "${toolCallId}"`.slice(
-        0,
-        maxCharacters
-      );
-    }
-
-    const consumedResults = matchedResults.length;
-    const nextResultOffset = resultOffset + consumedResults;
-    const hasMoreResults = nextResultOffset < totalMatches;
-    const range = consumedResults
-      ? `${resultOffset + 1}-${nextResultOffset}`
-      : `none (offset ${resultOffset} is past the final result)`;
-    const footerLines = [
-      "",
-      `[grep page: results ${range} of ${totalMatches}; ${consumedResults} returned; maxCharacters=${maxCharacters}]`,
-    ];
-
-    if (pagedLineNumbers.size > 0) {
-      footerLines.push(
-        `[Long source line(s) ${Array.from(pagedLineNumbers).join(", ")} were sliced. Repeat with options.lineCharacterOffset=${lineCharacterOffset + maxLineCharacters} to read their next characters.]`
-      );
-    }
-    if (hasMoreResults) {
-      footerLines.push(
-        `[More matches available. Repeat with options.resultOffset=${nextResultOffset}.]`
-      );
-    } else {
-      footerLines.push("[End of matches.]");
-    }
-
-    return (matchedResults.join("\n---\n") + footerLines.join("\n")).slice(
-      0,
-      maxCharacters
-    );
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error);
-    return `Grep Error: ${message.slice(0, 500)}`;
-  }
-}
-
-export const grepToolResponseDefinition: Tool = {
-  type: "function",
-  function: {
-    name: "grepToolResponse",
-    description:
-      "Search a stored tool response using a regular expression. Results and individual source lines are bounded and paginated. Follow the returned resultOffset or lineCharacterOffset instruction to retrieve more.",
-    parameters: {
-      type: "object",
-      positional: true,
-      properties: {
-        toolCallId: {
-          type: "string",
-          description: "The toolCallId of the stored tool response",
-        },
-        pattern: {
-          type: "string",
-          description: "Regular expression pattern to search for in the tool response",
-        },
-        options: {
-          type: "object",
-          description: "Optional grep, output-bound, and pagination settings.",
-          properties: {
-            ignoreCase: { type: "boolean", description: "Case-insensitive matching." },
-            invertMatch: { type: "boolean", description: "Return non-matching lines." },
-            contextBefore: { type: "number", description: "Context lines before a match (maximum 1000)." },
-            contextAfter: { type: "number", description: "Context lines after a match (maximum 1000)." },
-            maxResults: { type: "number", description: "Matches per page (default 100, maximum 1000)." },
-            resultOffset: { type: "number", description: "Zero-based match offset for the next result page." },
-            maxCharacters: { type: "number", description: "Response size (default 20000, hard maximum 50000)." },
-            lineCharacterOffset: { type: "number", description: "Character offset within every source line, for paging very long lines." },
-            maxLineCharacters: { type: "number", description: "Characters shown per source line (default 4000, maximum 10000)." },
-          },
-        },
-      },
-      required: ["toolCallId", "pattern"],
-    },
-  },
-};

package/src/processors/tools/index.ts

@@ -1,23 +0,0 @@
-export {
-  jqToolResponseDefinition,
-  executeJqQuery,
-  JqOptions,
-} from "./jqToolResponse";
-
-export {
-  grepToolResponseDefinition,
-  executeGrep,
-  GrepOptions,
-} from "./grepToolResponse";
-
-export {
-  tailToolResponseDefinition,
-  executeTail,
-  TailOptions,
-} from "./tailToolResponse";
-
-export {
-  listStoredToolResponsesDefinition,
-  executeListStoredToolResponses,
-  ListStoredToolResponsesOptions,
-} from "./listStoredToolResponses";

package/src/processors/tools/jqToolResponse.ts

@@ -1,159 +0,0 @@
-import { Tool } from "../../clients";
-import * as jq from "node-jq";
-import { paginateToolResponse } from "./boundedToolResponse";
-
-export interface JqOptions {
-  characterOffset?: number;
-  maxCharacters?: number;
-}
-
-/**
- * Attempts to parse content as JSON and returns parsed object if successful
- */
-function tryParseJson(content: string): any | null {
-  try {
-    return JSON.parse(content);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Recursively searches for JSON strings within an object and parses them
- */
-function parseNestedJsonStrings(obj: any): any {
-  if (typeof obj === "string") {
-    const parsed = tryParseJson(obj);
-    if (parsed) {
-      return parseNestedJsonStrings(parsed);
-    }
-    return obj;
-  }
-
-  if (Array.isArray(obj)) {
-    return obj.map((item) => parseNestedJsonStrings(item));
-  }
-
-  if (obj && typeof obj === "object") {
-    const result: any = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = parseNestedJsonStrings(value);
-    }
-    return result;
-  }
-
-  return obj;
-}
-
-/**
- * Retrieves and processes tool response data with JQ query
- */
-export async function executeJqQuery(
-  data: string,
-  toolCallId: string,
-  jqQuery: string,
-  availableIds: string[],
-  toolNameMap?: { [toolCallId: string]: string },
-  options?: JqOptions
-): Promise<string> {
-  if (!data) {
-    const idList = availableIds
-      .map((id) => {
-        const name = toolNameMap?.[id];
-        return name ? `${id} (${name})` : id;
-      })
-      .join("\n  - ");
-    return paginateToolResponse(
-      `Error: No tool response found for toolCallId "${toolCallId}". Call listStoredToolResponses to see all available responses with their tool names.\n\nAvailable toolCallIds:\n  - ${idList || "(none)"}`,
-      options,
-      "available toolCallId list"
-    );
-  }
-
-  try {
-    // First parse the stored string as JSON, then handle nested JSON strings
-    const jsonData = tryParseJson(data);
-    if (!jsonData) {
-      return paginateToolResponse(
-        `Error: Tool response data is not valid JSON for toolCallId "${toolCallId}"`,
-        options,
-        "jq input error"
-      );
-    }
-    const parsedData = parseNestedJsonStrings(jsonData);
-
-    // Execute JQ query
-    const result = await jq.run(jqQuery, parsedData, { input: "json" });
-
-    let rendered: string;
-    if (typeof result === "string") {
-      rendered = result;
-    } else if (typeof result === "number" || typeof result === "boolean") {
-      rendered = String(result);
-    } else if (result === null) {
-      rendered = "null";
-    } else {
-      rendered = JSON.stringify(result);
-    }
-    return paginateToolResponse(rendered, options, "jq result");
-  } catch (error: any) {
-    // If JQ fails, try to provide helpful error message
-    let errorMessage = `JQ Query Error: ${error.message}`;
-
-    // Try to parse as JSON to see if it's valid
-    const jsonObj = tryParseJson(data);
-    if (!jsonObj) {
-      errorMessage += `\nNote: The tool response data is not valid JSON. Raw data preview:\n${data.substring(
-        0,
-        300
-      )}...`;
-    } else {
-      errorMessage += `\nData structure preview:\n${JSON.stringify(
-        jsonObj,
-        null,
-        2
-      ).substring(0, 500)}...`;
-    }
-
-    return paginateToolResponse(errorMessage, options, "jq error");
-  }
-}
-
-export const jqToolResponseDefinition: Tool = {
-  type: "function",
-  function: {
-    name: "jqToolResponse",
-    description:
-      "Execute a JQ query on a stored tool response. Output is bounded to 20,000 characters by default; use options.characterOffset to page through a large result. Prefer a selective JQ query over paging a broad query. Call listStoredToolResponses first to discover the toolCallId. MCP responses are generally rooted at '.' (or '._data' when _mcp_format is true); standard built-in responses may be nested under '.content[0].text | fromjson'.",
-    parameters: {
-      type: "object",
-      positional: true,
-      properties: {
-        toolCallId: {
-          type: "string",
-          description: "The toolCallId of the stored tool response",
-        },
-        jqQuery: {
-          type: "string",
-          description:
-            "The JQ query to execute on the tool response data. For mcp_* tool responses (raw JSON object): '.children | map({id: .id, name: .name})' (extract fields from children array), '.children | map(select(.state == \"PENDING\")) | length' (count pending children), '.name' (get a top-level field). For compressed responses (._mcp_format true): '._data.children | map(.name)' or '._data | map(select(.state == \"PENDING\")) | length'. For standard built-in tool responses: '.content[0].text | fromjson | map(.title)' (extract titles from standard MCP array), '.content[0].text | fromjson | map(select(.createdAt > \"2025-01-01\"))' (filter by date).",
-        },
-        options: {
-          type: "object",
-          description: "Optional output pagination settings.",
-          properties: {
-            characterOffset: {
-              type: "number",
-              description: "Zero-based character offset into the rendered JQ result.",
-            },
-            maxCharacters: {
-              type: "number",
-              description: "Response size (default 20000, hard maximum 50000).",
-            },
-          },
-        },
-      },
-      required: ["toolCallId", "jqQuery"],
-    },
-  },
-};

package/src/processors/tools/listStoredToolResponses.ts

@@ -1,124 +0,0 @@
-import { Tool } from "../../clients";
-import { boundedInteger, paginateToolResponse } from "./boundedToolResponse";
-
-export interface ListStoredToolResponsesOptions {
-  resultOffset?: number;
-  maxResults?: number;
-  characterOffset?: number;
-  maxCharacters?: number;
-}
-
-export interface ToolResponseInfo {
-  toolCallId: string;
-  toolName: string;
-  size: number;
-  storedAt: number;
-  preview: string;
-}
-
-/**
- * List all stored tool responses with metadata
- */
-export async function executeListStoredToolResponses(
-  storage: { [toolCallId: string]: string },
-  metadataStorage: {
-    [toolCallId: string]: {
-      toolCallId: string;
-      originalLength: number;
-      storedAt: number;
-      toolName?: string;
-    };
-  },
-  toolNameMap: { [toolCallId: string]: string },
-  options?: ListStoredToolResponsesOptions
-): Promise<string> {
-  const toolCallIds = Object.keys(storage);
-
-  if (toolCallIds.length === 0) {
-    return "No tool responses have been stored yet.";
-  }
-
-  const responses: ToolResponseInfo[] = toolCallIds.map((toolCallId) => {
-    const data = storage[toolCallId];
-    const metadata = metadataStorage[toolCallId];
-    const toolName = toolNameMap[toolCallId] || "unknown";
-    
-    // Create a preview (first 100 characters)
-    const preview =
-      data.length > 100 ? data.substring(0, 100) + "..." : data;
-
-    return {
-      toolCallId,
-      toolName,
-      size: metadata?.originalLength || data.length,
-      storedAt: metadata?.storedAt || 0,
-      preview,
-    };
-  });
-
-  // Sort by most recent first
-  responses.sort((a, b) => b.storedAt - a.storedAt);
-
-  const resultOffset = boundedInteger(options?.resultOffset, 0, 0, responses.length);
-  const maxResults = boundedInteger(options?.maxResults, 100, 1, 1000);
-  const page = responses.slice(resultOffset, resultOffset + maxResults);
-  const output = page
-    .map((resp) => {
-      const date = new Date(resp.storedAt).toISOString();
-      return `
-Tool Call ID: ${resp.toolCallId.slice(0, 500)}
-Tool Name: ${resp.toolName.slice(0, 500)}
-Size: ${resp.size} characters
-Stored At: ${date}
-Preview: ${resp.preview}
----`;
-    })
-    .join("\n");
-
-  const nextOffset = resultOffset + page.length;
-  const footer = nextOffset < responses.length
-    ? `\n[More stored responses available. Repeat with options.resultOffset=${nextOffset}.]`
-    : "\n[End of stored responses.]";
-  return paginateToolResponse(
-    `Found ${responses.length} stored tool response(s); showing ${resultOffset + 1}-${nextOffset}:\n${output}${footer}`,
-    options,
-    "stored-response list"
-  );
-}
-
-export const listStoredToolResponsesDefinition: Tool = {
-  type: "function",
-  function: {
-    name: "listStoredToolResponses",
-    description:
-      "List a bounded page of stored tool responses with IDs, tool names, sizes, timestamps, and previews. Call this before jqToolResponse, grepToolResponse, or tailToolResponse to discover a toolCallId.",
-    parameters: {
-      type: "object",
-      positional: true,
-      properties: {
-        options: {
-          type: "object",
-          description: "Optional result and output pagination settings.",
-          properties: {
-            resultOffset: {
-              type: "number",
-              description: "Zero-based response offset (default 0).",
-            },
-            maxResults: {
-              type: "number",
-              description: "Responses per page (default 100, maximum 1000).",
-            },
-            characterOffset: {
-              type: "number",
-              description: "Character offset within the rendered page.",
-            },
-            maxCharacters: {
-              type: "number",
-              description: "Response size (default 20000, hard maximum 50000).",
-            },
-          },
-        },
-      },
-    },
-  },
-};

package/src/processors/tools/tailToolResponse.ts

@@ -1,148 +0,0 @@
-import { Tool } from "../../clients";
-import { boundedInteger, paginateToolResponse } from "./boundedToolResponse";
-
-export interface TailOptions {
-  lines?: number;
-  endLine?: number;
-  lineCharacterOffset?: number;
-  maxLineCharacters?: number;
-  characterOffset?: number;
-  maxCharacters?: number;
-}
-
-/**
- * Get the last n lines from a tool response
- */
-export async function executeTail(
-  data: string,
-  toolCallId: string,
-  availableIds: string[],
-  options?: TailOptions,
-  toolNameMap?: { [toolCallId: string]: string }
-): Promise<string> {
-  if (data === null || data === undefined) {
-    const idList = availableIds
-      .map((id) => {
-        const name = toolNameMap?.[id];
-        return name ? `${id} (${name})` : id;
-      })
-      .join("\n  - ");
-    return paginateToolResponse(
-      `Error: No tool response found for toolCallId "${toolCallId}". Call listStoredToolResponses to see all available responses with their tool names.\n\nAvailable toolCallIds:\n  - ${idList || "(none)"}`,
-      {
-        characterOffset: options?.characterOffset,
-        maxCharacters: options?.maxCharacters,
-      },
-      "available toolCallId list"
-    );
-  }
-
-  try {
-    const lines = data.split("\n");
-    const numLines = boundedInteger(options?.lines, 10, 0, 1000);
-
-    if (numLines <= 0) {
-      return "";
-    }
-
-    const endLine = boundedInteger(options?.endLine, lines.length, 1, lines.length);
-    const startIdx = Math.max(0, endLine - numLines);
-    const lineCharacterOffset = boundedInteger(
-      options?.lineCharacterOffset,
-      0,
-      0,
-      Number.MAX_SAFE_INTEGER
-    );
-    const maxLineCharacters = boundedInteger(
-      options?.maxLineCharacters,
-      4000,
-      100,
-      10_000
-    );
-    const longLines: number[] = [];
-
-    const formatted = lines.slice(startIdx, endLine).map((line, idx) => {
-      const lineNumber = startIdx + idx + 1;
-      const visible = line.slice(
-        lineCharacterOffset,
-        lineCharacterOffset + maxLineCharacters
-      );
-      if (lineCharacterOffset + maxLineCharacters < line.length) {
-        longLines.push(lineNumber);
-      }
-      return `${lineNumber}: ${visible}`;
-    });
-
-    const notes: string[] = [];
-    if (typeof options?.endLine === "number" && startIdx > 0) {
-      notes.push(`[Earlier lines available: repeat with options.endLine=${startIdx}.]`);
-    }
-    if (longLines.length > 0) notes.push(`[Long lines ${longLines.join(", ")} were sliced; repeat with options.lineCharacterOffset=${lineCharacterOffset + maxLineCharacters}.]`);
-    const rendered =
-      formatted.join("\n") +
-      (notes.length > 0 ? `\n\n${notes.join("\n")}` : "");
-    return paginateToolResponse(
-      rendered,
-      {
-        characterOffset: options?.characterOffset,
-        maxCharacters: options?.maxCharacters,
-      },
-      "tail result"
-    );
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error);
-    return `Tail Error: ${message.slice(0, 500)}`;
-  }
-}
-
-export const tailToolResponseDefinition: Tool = {
-  type: "function",
-  function: {
-    name: "tailToolResponse",
-    description:
-      "Get a bounded page of lines from the end of a stored tool response. Use endLine to page backward and lineCharacterOffset to page through unusually long lines.",
-    parameters: {
-      type: "object",
-      positional: true,
-      properties: {
-        toolCallId: {
-          type: "string",
-          description: "The toolCallId of the stored tool response.",
-        },
-        options: {
-          type: "object",
-          description: "Optional tail and pagination settings.",
-          properties: {
-            lines: {
-              type: "number",
-              description: "Lines per page (default 10, maximum 1000).",
-            },
-            endLine: {
-              type: "number",
-              description:
-                "1-based inclusive line at which the page ends; use the returned value to page backward.",
-            },
-            lineCharacterOffset: {
-              type: "number",
-              description: "Character offset within each source line.",
-            },
-            maxLineCharacters: {
-              type: "number",
-              description:
-                "Characters shown per line (default 4000, maximum 10000).",
-            },
-            characterOffset: {
-              type: "number",
-              description: "Character offset within the rendered tail page.",
-            },
-            maxCharacters: {
-              type: "number",
-              description: "Response size (default 20000, hard maximum 50000).",
-            },
-          },
-        },
-      },
-      required: ["toolCallId"],
-    },
-  },
-};

package/src/prompts/BasicCodeDocumenter.ts

@@ -1 +0,0 @@
-export default "Summarize this code, with a focus on dependencies, types, models, classes, comments, and examples. Include snippets of core concepts if relevant. \n\n {text}";

package/src/prompts/BasicProjectDocumenter.ts

@@ -1 +0,0 @@
-export default "Summarize this project documentation, with the goal of creating a useful primer for others to understand the project in a technical way. Focus on how the different pieces of the project interact with each other, design patterns, naming conventions, etc. \n\n {text}";

package/src/prompts/EmbeddingSeachHelper.ts

@@ -1 +0,0 @@
-export default `Given this file, create a short summary of what the file contains, and include a list of questions this file would help answer\n\n{text}`;