user-docs

/**
 * skip_doc — remove a read_doc result from the API context.
 *
 * Writes the given read_id to read_doc-skips.json in chatWd.
 * The preprocessor reads this list before each API call and filters
 * out the matching assistant + tool message pair from the messages array.
 * The local chat history (conversation.json) is NOT modified.
 */

import { tool, type Tool, type ToolsProviderController } from "@lmstudio/sdk";
// @ts-ignore — zod/lib re-export chain breaks with NodeNext; runtime is fine
import { z } from "zod";
import path from "node:path";
import fs from "node:fs";
import { formatToolMetaBlock } from "../core-bundle.mjs";

const SKIPS_FILE = "read_doc-skips.json";

export function createSkipDocTool(ctl: ToolsProviderController): Tool {
  return tool({
    name: "skip_doc",
    description: `Remove a previously read document from the API context to save tokens.

After calling read_doc, you receive a read_id (<!-- read_id: XXXXXX -->).
Passing that read_id to skip_doc tells the preprocessor to exclude the
corresponding read_doc call and its response from future API requests.

The chat history visible in LM Studio is NOT affected — only the API payload is filtered.

Use this tool when:
- A document was read earlier but is no longer relevant to the current task
- You want to free up context window space before reading another document

Returns:
- Confirmation that the read_id was added to the skip list

${formatToolMetaBlock()}`,
    parameters: {
      read_id: z
        .string()
        .describe(
          "The read_id returned by read_doc (the 6-character hex value inside <!-- read_id: XXXXXX -->)."
        ),
    },
    implementation: async (args) => {
      const chatWd = ctl.getWorkingDirectory();
      if (typeof chatWd !== "string" || !chatWd.trim()) {
        return "Error: Working directory not available.";
      }

      const readId = args.read_id?.trim();
      if (!readId) {
        return "Error: read_id must not be empty.";
      }

      const skipsPath = path.join(chatWd, SKIPS_FILE);

      // Read existing skip list
      let skips: string[] = [];
      if (fs.existsSync(skipsPath)) {
        try {
          const raw = fs.readFileSync(skipsPath, "utf8");
          const parsed = JSON.parse(raw);
          if (Array.isArray(parsed)) {
            skips = parsed.filter((s) => typeof s === "string");
          }
        } catch {
          // Start fresh if file is corrupt
          skips = [];
        }
      }

      if (skips.includes(readId)) {
        return `read_id "${readId}" is already in the skip list.`;
      }

      skips.push(readId);

      try {
        fs.writeFileSync(skipsPath, JSON.stringify(skips, null, 2), "utf8");
      } catch (err) {
        return `Error: Could not write skip list — ${err instanceof Error ? err.message : String(err)}`;
      }

      return `Skipped read_id "${readId}" from API context. The document will be excluded from future API calls in this chat.`;
    },
  });
}