prism-mcp-server 1.5.0

package/src/tools/compactionHandler.ts

@@ -0,0 +1,313 @@
+/**
+ * Ledger Compaction Handler (v1.5.0 — Enhancement #2)
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * REVIEWER NOTE: This module implements automatic rollup of old
+ * ledger entries to prevent unbounded growth.
+ *
+ * THE PROBLEM:
+ *   session_ledger is append-only. After months of heavy use,
+ *   the "deep" context loading could return thousands of tokens
+ *   or hit API payload limits. There's no automatic cleanup.
+ *
+ * THE SOLUTION:
+ *   When triggered, this handler:
+ *   1. Calls get_compaction_candidates() to find bloated projects
+ *   2. For each project: fetches old entries, summarizes via Gemini
+ *   3. Inserts a rollup entry with is_rollup=true
+ *   4. Marks old entries with archived_at (soft-delete)
+ *
+ * CHUNKING STRATEGY:
+ *   If a project has 50 entries to compact, we don't send all 50
+ *   to Gemini at once (might blow past token limits). Instead:
+ *   - Chunk into groups of 10
+ *   - Summarize each chunk → get 5 sub-summaries
+ *   - If 5+ sub-summaries exist, summarize those into a final rollup
+ *   This recursive strategy ensures we never exceed Gemini's context window.
+ *
+ * SAFETY:
+ *   - Old entries are soft-deleted (archived_at set), not hard-deleted
+ *   - The rollup entry preserves all keywords and decisions from originals
+ *   - Reversible: set archived_at=NULL to restore original entries
+ *   - Dry run mode available to preview before executing
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+import { supabaseRpc, supabaseGet, supabasePost, supabasePatch } from "../utils/supabaseApi.js";
+import { GOOGLE_API_KEY, PRISM_USER_ID } from "../config.js";
+import { GoogleGenerativeAI } from "@google/generative-ai";
+
+// ─── Constants ────────────────────────────────────────────────
+
+// REVIEWER NOTE: Chunk size for sending entries to Gemini.
+// 10 entries × ~500 chars each = ~5000 chars per chunk,
+// well within Gemini's 1M token context window.
+// Keeping chunks small ensures consistent summarization quality.
+const COMPACTION_CHUNK_SIZE = 10;
+
+// Maximum entries to compact in a single tool call
+// REVIEWER NOTE: Safety limit to prevent the tool from running
+// for too long on a single invocation. If more entries need
+// compacting, the tool can be called again.
+const MAX_ENTRIES_PER_RUN = 100;
+
+// ─── Type Guard ───────────────────────────────────────────────
+
+export function isCompactLedgerArgs(
+  args: unknown
+): args is {
+  project?: string;
+  threshold?: number;
+  keep_recent?: number;
+  dry_run?: boolean;
+} {
+  return typeof args === "object" && args !== null;
+}
+
+// ─── Gemini Summarization ─────────────────────────────────────
+
+/**
+ * Summarize a batch of ledger entries using Gemini.
+ *
+ * REVIEWER NOTE: The prompt is carefully designed to preserve
+ * important information (decisions, file changes, error resolutions)
+ * while condensing narrative. The output format matches what we
+ * store in a rollup entry's summary field.
+ */
+async function summarizeEntries(entries: any[]): Promise<string> {
+  if (!GOOGLE_API_KEY) {
+    throw new Error("Cannot compact ledger: GOOGLE_API_KEY required for Gemini summarization");
+  }
+
+  const genAI = new GoogleGenerativeAI(GOOGLE_API_KEY);
+  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
+
+  // Build a concise representation of each entry for the prompt
+  const entriesText = entries.map((e, i) =>
+    `[${i + 1}] ${e.session_date || "unknown date"}: ${e.summary || "no summary"}\n` +
+    (e.decisions?.length ? `  Decisions: ${e.decisions.join("; ")}\n` : "") +
+    (e.files_changed?.length ? `  Files: ${e.files_changed.join(", ")}\n` : "")
+  ).join("\n");
+
+  const prompt =
+    `You are compressing a session history log. Summarize these ${entries.length} ` +
+    `work sessions into a single concise paragraph (max 500 words).\n\n` +
+    `PRESERVE: key decisions, important file changes, error resolutions, ` +
+    `architecture changes, and any recurring patterns.\n` +
+    `OMIT: routine operations, intermediate debugging steps, and redundant details.\n\n` +
+    `Sessions to summarize:\n${entriesText}\n\n` +
+    `Provide ONLY the summary paragraph, no headers or formatting.`;
+
+  // REVIEWER NOTE: Using truncation to prevent exceeding API limits.
+  // The prompt itself is structured to stay well within limits, but
+  // this is an extra safety net.
+  const truncatedPrompt = prompt.substring(0, 30000);
+
+  const result = await model.generateContent(truncatedPrompt);
+  const response = result.response;
+  return response.text();
+}
+
+// ─── Main Handler ─────────────────────────────────────────────
+
+/**
+ * Compact old ledger entries into rollup summaries.
+ *
+ * REVIEWER NOTE: This handler can be called in two modes:
+ *   1. With a specific project → compact only that project
+ *   2. Without a project → auto-detect all candidates
+ *   3. With dry_run=true → preview what would be compacted
+ */
+export async function compactLedgerHandler(args: unknown) {
+  if (!isCompactLedgerArgs(args)) {
+    throw new Error("Invalid arguments for session_compact_ledger");
+  }
+
+  const {
+    project,
+    threshold = 50,
+    keep_recent = 10,
+    dry_run = false,
+  } = args;
+
+  console.error(
+    `[compact_ledger] ${dry_run ? "DRY RUN: " : ""}` +
+    `project=${project || "auto-detect"}, threshold=${threshold}, keep_recent=${keep_recent}`
+  );
+
+  // Step 1: Find candidates
+  let candidates: any[];
+  if (project) {
+    // If specific project, check it directly
+    // v1.5.0: Scope direct query to user_id
+    const entries = await supabaseGet("session_ledger", {
+      project: `eq.${project}`,
+      user_id: `eq.${PRISM_USER_ID}`,
+      "archived_at": "is.null",
+      "is_rollup": "eq.false",
+      select: "id",
+    });
+    const count = Array.isArray(entries) ? entries.length : 0;
+    if (count <= threshold) {
+      return {
+        content: [{
+          type: "text",
+          text: `✅ Project "${project}" has ${count} active entries ` +
+            `(threshold: ${threshold}). No compaction needed.`,
+        }],
+        isError: false,
+      };
+    }
+    candidates = [{ project, total_entries: count, to_compact: count - keep_recent }];
+  } else {
+    // Auto-detect candidates using the RPC
+    // v1.5.0: Pass p_user_id for multi-tenant isolation
+    const result = await supabaseRpc("get_compaction_candidates", {
+      p_threshold: threshold,
+      p_keep_recent: keep_recent,
+      p_user_id: PRISM_USER_ID,
+    });
+    candidates = Array.isArray(result) ? result : [];
+  }
+
+  if (candidates.length === 0) {
+    return {
+      content: [{
+        type: "text",
+        text: `✅ No projects exceed the compaction threshold (${threshold} entries). ` +
+          `All clear!`,
+      }],
+      isError: false,
+    };
+  }
+
+  // Dry run: just report candidates
+  if (dry_run) {
+    const summary = candidates.map(c =>
+      `• ${c.project}: ${c.total_entries} entries (${c.to_compact} would be compacted)`
+    ).join("\n");
+
+    return {
+      content: [{
+        type: "text",
+        text: `🔍 Compaction preview (dry run):\n\n${summary}\n\n` +
+          `Run without dry_run to execute compaction.`,
+      }],
+      isError: false,
+    };
+  }
+
+  // Step 2: Compact each candidate project
+  const results: string[] = [];
+
+  for (const candidate of candidates) {
+    const proj = candidate.project;
+    const toCompact = Math.min(candidate.to_compact, MAX_ENTRIES_PER_RUN);
+
+    console.error(`[compact_ledger] Compacting ${toCompact} entries for "${proj}"`);
+
+    // Fetch oldest entries (the ones to be rolled up)
+    // v1.5.0: Scope to user_id
+    const oldEntries = await supabaseGet("session_ledger", {
+      project: `eq.${proj}`,
+      user_id: `eq.${PRISM_USER_ID}`,
+      "archived_at": "is.null",
+      "is_rollup": "eq.false",
+      order: "created_at.asc",
+      limit: String(toCompact),
+      select: "id,summary,decisions,files_changed,keywords,session_date",
+    });
+
+    if (!Array.isArray(oldEntries) || oldEntries.length === 0) {
+      results.push(`• ${proj}: no entries to compact`);
+      continue;
+    }
+
+    // Step 3: Chunked summarization
+    // REVIEWER NOTE: We chunk entries to avoid exceeding Gemini's
+    // token limits. Each chunk is summarized independently, then
+    // if multiple chunks exist, the sub-summaries are summarized again.
+    const chunks: any[][] = [];
+    for (let i = 0; i < oldEntries.length; i += COMPACTION_CHUNK_SIZE) {
+      chunks.push(oldEntries.slice(i, i + COMPACTION_CHUNK_SIZE));
+    }
+
+    let finalSummary: string;
+
+    if (chunks.length === 1) {
+      // Single chunk — summarize directly
+      finalSummary = await summarizeEntries(chunks[0]);
+    } else {
+      // Multiple chunks — recursive summarization
+      // First pass: summarize each chunk
+      const chunkSummaries = await Promise.all(
+        chunks.map(chunk => summarizeEntries(chunk))
+      );
+
+      // Second pass: summarize the summaries
+      // REVIEWER NOTE: This recursive approach handles arbitrarily
+      // large batches. In practice, MAX_ENTRIES_PER_RUN=100 with
+      // COMPACTION_CHUNK_SIZE=10 means at most 10 sub-summaries,
+      // which is well within Gemini's limits.
+      const metaEntries = chunkSummaries.map((s, i) => ({
+        session_date: `chunk ${i + 1}`,
+        summary: s,
+        decisions: [],
+        files_changed: [],
+      }));
+      finalSummary = await summarizeEntries(metaEntries);
+    }
+
+    // Collect all unique keywords from rolled-up entries
+    const allKeywords = [...new Set(
+      oldEntries.flatMap((e: any) => e.keywords || [])
+    )];
+
+    // Collect all unique files changed
+    const allFiles = [...new Set(
+      oldEntries.flatMap((e: any) => e.files_changed || [])
+    )];
+
+    // Step 4: Insert rollup entry
+    // v1.5.0: Include user_id in rollup entry
+    await supabasePost("session_ledger", {
+      project: proj,
+      user_id: PRISM_USER_ID,
+      summary: `[ROLLUP of ${oldEntries.length} sessions] ${finalSummary}`,
+      keywords: allKeywords,
+      files_changed: allFiles,
+      decisions: [`Rolled up ${oldEntries.length} sessions on ${new Date().toISOString()}`],
+      is_rollup: true,
+      rollup_count: oldEntries.length,
+      // REVIEWER NOTE: We need to provide required fields for the table.
+      // These are set to sensible defaults for rollup entries.
+      title: `Session Rollup (${oldEntries.length} entries)`,
+      agent_name: "prism-compactor",
+      conversation_id: `rollup-${Date.now()}`,
+    });
+
+    // Step 5: Archive old entries (soft-delete)
+    const entryIds = oldEntries.map((e: any) => e.id);
+    for (const id of entryIds) {
+      await supabasePatch(
+        "session_ledger",
+        { archived_at: new Date().toISOString() },
+        { id: `eq.${id}` }
+      );
+    }
+
+    results.push(
+      `• ${proj}: ${oldEntries.length} entries → 1 rollup ` +
+      `(${allKeywords.length} keywords preserved)`
+    );
+  }
+
+  return {
+    content: [{
+      type: "text",
+      text: `🧹 Ledger compaction complete:\n\n${results.join("\n")}\n\n` +
+        `Original entries are archived (soft-deleted), not permanently removed.`,
+    }],
+    isError: false,
+  };
+}

package/src/tools/definitions.ts

@@ -0,0 +1,367 @@
+/**
+ * Tool Definitions (Schemas)
+ *
+ * This file defines the SHAPE of each tool — its name, description, and
+ * what input arguments it accepts. These definitions are sent to the AI client
+ * (e.g., Claude Desktop) so it knows what tools are available and how to call them.
+ *
+ * Each tool definition has:
+ *   - name:         Unique identifier used to route calls in server.ts
+ *   - description:  Human-readable text shown to the AI so it knows when to use the tool
+ *   - inputSchema:  JSON Schema describing the accepted arguments (types, required fields, defaults)
+ *
+ * The corresponding IMPLEMENTATIONS (what the tools actually do) are in handlers.ts.
+ *
+ * Tool Categories:
+ *   1. Search Tools       — brave_web_search, brave_local_search
+ *   2. Code Mode Tools    — brave_web_search_code_mode, brave_local_search_code_mode, code_mode_transform
+ *   3. AI Analysis Tools  — brave_answers, gemini_research_paper_analysis
+ *   4. Session Memory     — defined separately in sessionMemoryDefinitions.ts (optional)
+ *
+ * Adding a new tool:
+ *   1. Define it here (schema + type guard)
+ *   2. Implement the handler in handlers.ts
+ *   3. Export both from tools/index.ts
+ *   4. Add a case to the switch statement in server.ts
+ */
+
+import { type Tool } from "@modelcontextprotocol/sdk/types.js";
+
+// ─── Search Tools ─────────────────────────────────────────────
+
+// Code Mode: Search + JavaScript extraction
+// The "code mode" pattern works like this:
+//   1. Perform a regular Brave search to get raw API JSON
+//   2. Run user-provided JavaScript code against that JSON in a QuickJS sandbox
+//   3. Return only the extracted/transformed output (much smaller than the full response)
+// This dramatically reduces token usage when the AI only needs specific fields from search results.
+
+export const BRAVE_WEB_SEARCH_CODE_MODE_TOOL: Tool = {
+  name: "brave_web_search_code_mode",
+  description:
+    "Performs a web search using the Brave Search API, and then runs a custom JavaScript code string against the RAW API RESPONSE in a secure QuickJS sandbox. " +
+    "This drastically reduces context window usage by only returning the output of your script. " +
+    "Use this for broad information gathering, recent events, or when you need diverse web sources and only need specific parts of the result. " +
+    "Your script should read the 'DATA' global variable (a JSON string of the API response), process it, and use console.log() to print the desired output.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Search query (max 400 chars, 50 words)",
+      },
+      count: {
+        type: "number",
+        description: "Number of results (1-20, default 10)",
+        default: 10,
+      },
+      offset: {
+        type: "number",
+        description: "Pagination offset (max 9, default 0)",
+        default: 0,
+      },
+      code: {
+        type: "string",
+        description: "JavaScript code to execute against the 'DATA' variable. E.g. `const r = JSON.parse(DATA); console.log(r.web.results.map(x => x.title).join(', '));`",
+      },
+      language: {
+        type: "string",
+        description: "Language of the code. Only 'javascript' is supported.",
+        default: "javascript",
+      }
+    },
+    required: ["query", "code"],
+  },
+};
+
+// Standard web search — returns formatted text results (title, description, URL).
+// This is the simplest search tool. For extracting specific fields, use the code mode variant above.
+export const WEB_SEARCH_TOOL: Tool = {
+  name: "brave_web_search",
+  description:
+    "Performs a web search using the Brave Search API, ideal for general queries, news, articles, and online content. " +
+    "Use this for broad information gathering, recent events, or when you need diverse web sources. " +
+    "Supports pagination, content filtering, and freshness controls. " +
+    "Maximum 20 results per request, with offset for pagination. ",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Search query (max 400 chars, 50 words)",
+      },
+      count: {
+        type: "number",
+        description: "Number of results (1-20, default 10)",
+        default: 10,
+      },
+      offset: {
+        type: "number",
+        description: "Pagination offset (max 9, default 0)",
+        default: 0,
+      },
+    },
+    required: ["query"],
+  },
+};
+
+// ─── Local/Business Search Tools ──────────────────────────────
+
+// Searches for physical businesses and places (restaurants, stores, services).
+// Returns structured data: name, address, phone, rating, hours, price range.
+// If no local results are found, automatically falls back to a regular web search.
+export const LOCAL_SEARCH_TOOL: Tool = {
+  name: "brave_local_search",
+  description:
+    "Searches for local businesses and places using Brave's Local Search API. " +
+    "Best for queries related to physical locations, businesses, restaurants, services, etc. " +
+    "Returns detailed information including:\n" +
+    "- Business names and addresses\n" +
+    "- Ratings and review counts\n" +
+    "- Phone numbers and opening hours\n" +
+    "Use this when the query implies 'near me' or mentions specific locations. " +
+    "Automatically falls back to web search if no local results are found.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Local search query (e.g. 'pizza near Central Park')",
+      },
+      count: {
+        type: "number",
+        description: "Number of results (1-20, default 5)",
+        default: 5,
+      },
+    },
+    required: ["query"],
+  },
+};
+
+// Code mode variant for local search — same pattern as web search code mode.
+// Useful when you only need specific fields from the detailed POI (Point of Interest) data.
+export const BRAVE_LOCAL_SEARCH_CODE_MODE_TOOL: Tool = {
+  name: "brave_local_search_code_mode",
+  description:
+    "Performs a local search using Brave APIs, and then runs a custom JavaScript code string against the RAW API RESPONSE in a secure QuickJS sandbox. " +
+    "This reduces context window usage by only returning the output of your script. " +
+    "Use this for local/business lookups when you only need specific fields from large local payloads. " +
+    "Your script should read the 'DATA' global variable (a JSON string payload) and use console.log() to print the desired output.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Local search query (e.g. 'pizza near Central Park')",
+      },
+      count: {
+        type: "number",
+        description: "Number of results (1-20, default 5)",
+        default: 5,
+      },
+      code: {
+        type: "string",
+        description: "JavaScript code to execute against the 'DATA' variable.",
+      },
+      language: {
+        type: "string",
+        description: "Language of the code. Only 'javascript' is supported.",
+        default: "javascript",
+      },
+    },
+    required: ["query", "code"],
+  },
+};
+
+// ─── Universal Transform Tool ─────────────────────────────────
+
+// This is NOT tied to Brave Search — it works with output from ANY MCP tool.
+// Pass it raw data from any source + a JavaScript extraction script,
+// and it returns only the fields you need. Great for reducing token usage.
+export const CODE_MODE_TRANSFORM_TOOL: Tool = {
+  name: "code_mode_transform",
+  description:
+    "A universal code-mode transformer. Takes RAW TEXT or JSON output from ANY MCP tool (GitHub, Firecrawl, chrome-devtools, camoufox, codegraphcontext, videoMcp, arxiv, etc.) " +
+    "and runs a custom JavaScript code string against it in a secure QuickJS sandbox. " +
+    "Use this as a second step after calling any tool that returns large payloads — pass the raw output as 'data' and a JS extraction script as 'code'. " +
+    "Your script reads the 'DATA' global variable (a string of the tool output) and uses console.log() to print only the fields you need. " +
+    "Typical use cases: extract only issue titles/IDs from GitHub list_issues, pull specific selectors from DOM snapshots, summarize crawl results, extract timestamps from video transcripts.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      data: {
+        type: "string",
+        description: "The raw text or JSON output from another MCP tool to process.",
+      },
+      code: {
+        type: "string",
+        description:
+          "JavaScript code to execute. The 'DATA' global variable contains the raw data string. Use console.log() to output your extraction. " +
+          "Example: `var d = JSON.parse(DATA); console.log(d.items.map(function(i){return i.title}).join('\\n'));`",
+      },
+      language: {
+        type: "string",
+        description: "Language of the code. Only 'javascript' is supported.",
+        default: "javascript",
+      },
+      source_tool: {
+        type: "string",
+        description: "Optional. Name of the MCP tool that produced the data (for logging/metrics only).",
+      },
+    },
+    required: ["data", "code"],
+  },
+};
+
+// ─── AI Analysis Tools ────────────────────────────────────────
+
+// AI-grounded answers — uses Brave's AI grounding endpoint (OpenAI-compatible API).
+// Returns concise, web-grounded answers rather than raw search results.
+// Requires a separate BRAVE_ANSWERS_API_KEY.
+export const BRAVE_ANSWERS_TOOL: Tool = {
+  name: "brave_answers",
+  description:
+    "Returns direct AI answers grounded in Brave Search using Brave AI Grounding. " +
+    "Uses an OpenAI-compatible chat completions endpoint and is best for concise answer generation with live web grounding.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Question or prompt to answer",
+      },
+      model: {
+        type: "string",
+        description: "Model name for Brave AI Grounding (default: brave)",
+        default: "brave",
+      },
+    },
+    required: ["query"],
+  },
+};
+
+// Analyzes academic research papers using Google's Gemini model.
+// Supports multiple analysis types: summary, critique, literature review, key findings.
+// Requires GOOGLE_API_KEY to be configured.
+export const RESEARCH_PAPER_ANALYSIS_TOOL: Tool = {
+  name: "gemini_research_paper_analysis",
+  description:
+    "Performs in-depth analysis of research papers using Google's Gemini-2.0-flash model. " +
+    "Ideal for academic research, literature reviews, and deep understanding of scientific papers. " +
+    "Can extract key findings, provide critical evaluation, summarize complex research, " +
+    "and place papers within the broader research landscape. " +
+    "Best for long-form academic content that requires expert analysis.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      paperContent: {
+        type: "string",
+        description: "The full text of the research paper to analyze",
+      },
+      analysisType: {
+        type: "string",
+        description: "Type of analysis to perform (summary, critique, literature review, key findings, or comprehensive)",
+        enum: ["summary", "critique", "literature review", "key findings", "comprehensive"],
+        default: "comprehensive",
+      },
+      additionalContext: {
+        type: "string",
+        description: "Optional additional context or specific questions to guide the analysis",
+      },
+    },
+    required: ["paperContent"],
+  },
+};
+
+// ─── Type Guards ──────────────────────────────────────────────
+//
+// Type guards validate that incoming tool arguments match the expected shape.
+// They are used by handlers to safely access argument properties without
+// runtime errors. Each guard checks that required fields exist and are
+// the correct type.
+//
+// Pattern: if (!isMyToolArgs(args)) throw new Error("Invalid arguments");
+
+/** Validates arguments for brave_web_search */
+export function isBraveWebSearchArgs(
+  args: unknown
+): args is { query: string; count?: number; offset?: number } {
+  return (
+    typeof args === "object" &&
+    args !== null &&
+    "query" in args &&
+    typeof (args as { query: string }).query === "string"
+  );
+}
+
+export function isBraveLocalSearchArgs(
+  args: unknown
+): args is { query: string; count?: number } {
+  return (
+    typeof args === "object" &&
+    args !== null &&
+    "query" in args &&
+    typeof (args as { query: string }).query === "string"
+  );
+}
+
+export function isBraveAnswersArgs(
+  args: unknown
+): args is { query: string; model?: string } {
+  return (
+    typeof args === "object" &&
+    args !== null &&
+    "query" in args &&
+    typeof (args as { query: string }).query === "string"
+  );
+}
+
+export function isGeminiResearchPaperAnalysisArgs(
+  args: unknown
+): args is { paperContent: string; analysisType?: string; additionalContext?: string } {
+  return (
+    typeof args === "object" &&
+    args !== null &&
+    "paperContent" in args &&
+    typeof (args as { paperContent: string }).paperContent === "string"
+  );
+}
+
+export function isBraveWebSearchCodeModeArgs(
+  args: unknown
+): args is { query: string; count?: number; offset?: number; code: string; language?: string } {
+  return (
+    typeof args === "object" &&
+    args !== null &&
+    "query" in args &&
+    typeof (args as { query: string }).query === "string" &&
+    "code" in args &&
+    typeof (args as { code: string }).code === "string"
+  );
+}
+
+export function isBraveLocalSearchCodeModeArgs(
+  args: unknown
+): args is { query: string; count?: number; code: string; language?: string } {
+  return (
+    typeof args === "object" &&
+    args !== null &&
+    "query" in args &&
+    typeof (args as { query: string }).query === "string" &&
+    "code" in args &&
+    typeof (args as { code: string }).code === "string"
+  );
+}
+
+export function isCodeModeTransformArgs(
+  args: unknown
+): args is { data: string; code: string; language?: string; source_tool?: string } {
+  return (
+    typeof args === "object" &&
+    args !== null &&
+    "data" in args &&
+    typeof (args as { data: string }).data === "string" &&
+    "code" in args &&
+    typeof (args as { code: string }).code === "string"
+  );
+}