surgent 0.7.0-alpha.0

package/src/optimizers/deduplicator/resources.ts

@@ -0,0 +1,77 @@
+import { realpathSync } from "node:fs";
+import { normalize, resolve } from "node:path";
+import { isRecord } from "../../utils.js";
+import { parseInspectToolDetails } from "../inspector/helpers.js";
+import type { Range } from "../inspector/types.js";
+
+export interface ResourceCoverage {
+  resource: string;
+  range: Range;
+}
+
+function getResultText(message: Record<string, unknown>): string | undefined {
+  if (!Array.isArray(message.content) || message.content.length !== 1) return;
+
+  const content = message.content[0];
+  if (!isRecord(content) || content.type !== "text" || typeof content.text !== "string") return;
+  return content.text;
+}
+
+function normalizeResourcePath(sourcePath: string, cwd: string): string {
+  const absolutePath = resolve(cwd, sourcePath);
+  try {
+    return normalize(realpathSync(absolutePath));
+  } catch {
+    return normalize(absolutePath);
+  }
+}
+
+export function getResourceCoverage(
+  toolName: string,
+  input: Record<string, unknown>,
+  result: unknown,
+  cwd: string,
+): ResourceCoverage | undefined {
+  if (!isRecord(result)) return;
+
+  if (toolName === "inspect") {
+    const inspected = parseInspectToolDetails(result.details);
+    if (!inspected) return;
+    return {
+      resource: normalizeResourcePath(inspected.path, cwd),
+      range: inspected.range,
+    };
+  }
+
+  if (toolName !== "read") return;
+  const sourcePath = input.path;
+  const offset = input.offset;
+  if (typeof sourcePath !== "string" || sourcePath.length === 0) return;
+  if (
+    offset !== undefined &&
+    (typeof offset !== "number" || !Number.isInteger(offset) || offset < 1)
+  ) {
+    return;
+  }
+
+  const details = isRecord(result.details) ? result.details : undefined;
+  const truncation = details?.truncation;
+  if (truncation !== undefined && !isRecord(truncation)) return;
+  if (isRecord(truncation) && truncation.firstLineExceedsLimit === true) return;
+
+  const resultText = getResultText(result);
+  if (resultText === undefined) return;
+  const continuation = resultText.match(/\n\n\[[^\n]*Use offset=\d+ to continue\.\]$/)?.[0];
+  const visibleText = continuation ? resultText.slice(0, -continuation.length) : resultText;
+  const outputLines =
+    isRecord(truncation) && truncation.truncated === true
+      ? truncation.outputLines
+      : visibleText.split("\n").length;
+  if (typeof outputLines !== "number" || !Number.isInteger(outputLines) || outputLines <= 0) return;
+
+  const start = typeof offset === "number" ? offset : 1;
+  return {
+    resource: normalizeResourcePath(sourcePath, cwd),
+    range: [start, start + outputLines - 1],
+  };
+}

package/src/optimizers/deduplicator/state.ts

@@ -0,0 +1,119 @@
+import {
+  getBranchEntries,
+  getEntryId,
+  getLastEntryId,
+  getMessage,
+  getToolResultMessage,
+} from "../entries.js";
+import { isRecord } from "../../utils.js";
+import { hasFullCoverage } from "./helpers.js";
+import { getResourceCoverage } from "./resources.js";
+import type { DeduplicatorState, ResourceResult } from "./types.js";
+
+function collectToolCallInputs(
+  activeEntries: Record<string, unknown>[],
+): Map<string, Record<string, unknown>> {
+  const inputsByCallId = new Map<string, Record<string, unknown>>();
+
+  for (const entry of activeEntries) {
+    const message = getMessage(entry);
+    if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+
+    for (const block of message.content) {
+      if (!isRecord(block) || block.type !== "toolCall") continue;
+      if (typeof block.id !== "string" || !isRecord(block.arguments)) continue;
+      inputsByCallId.set(block.id, block.arguments);
+    }
+  }
+
+  return inputsByCallId;
+}
+
+function collectResourceResults(
+  activeEntries: Record<string, unknown>[],
+  inputsByCallId: Map<string, Record<string, unknown>>,
+  cwd: string,
+): ResourceResult[] {
+  const results: ResourceResult[] = [];
+  for (const entry of activeEntries) {
+    const entryId = getEntryId(entry);
+    const message = getToolResultMessage(entry);
+    if (
+      !entryId ||
+      !message ||
+      message.isError === true ||
+      typeof message.toolCallId !== "string"
+    ) {
+      continue;
+    }
+
+    const input = inputsByCallId.get(message.toolCallId);
+    if (!input || (message.toolName !== "read" && message.toolName !== "inspect")) continue;
+
+    const coverage = getResourceCoverage(message.toolName, input, message, cwd);
+    if (!coverage) continue;
+    results.push({
+      entryId,
+      range: coverage.range,
+      resource: coverage.resource,
+      toolCallId: message.toolCallId,
+      prunable: true,
+    });
+  }
+  return results;
+}
+
+function collectReplacementsById(results: ResourceResult[]): Map<string, string[]> {
+  const retainedByResource = new Map<string, ResourceResult[]>();
+  const replacementsById = new Map<string, string[]>();
+
+  for (let index = results.length - 1; index >= 0; index -= 1) {
+    const result = results[index]!;
+    const retained = retainedByResource.get(result.resource) ?? [];
+    const covering = retained.filter(
+      (candidate) => candidate.range[0] <= result.range[1] && candidate.range[1] >= result.range[0],
+    );
+
+    if (
+      hasFullCoverage(
+        result.range,
+        covering.map(({ range }) => range),
+      )
+    ) {
+      if (result.prunable) {
+        replacementsById.set(result.entryId, [
+          ...new Set(covering.map((candidate) => candidate.entryId)),
+        ]);
+      }
+      continue;
+    }
+    retained.push(result);
+    retainedByResource.set(result.resource, retained);
+  }
+
+  return replacementsById;
+}
+
+export function buildDeduplicatorState(
+  entries: Record<string, unknown>[],
+  leafId: string | null,
+  cwd: string,
+): DeduplicatorState {
+  let activeEntries = getBranchEntries(entries, leafId);
+  if (activeEntries.length === 0 && leafId !== null) {
+    activeEntries = getBranchEntries(entries, getLastEntryId(entries));
+  }
+
+  const results = collectResourceResults(activeEntries, collectToolCallInputs(activeEntries), cwd);
+  const replacementsById = collectReplacementsById(results);
+  const replacements = new Map<string, string[]>();
+
+  for (const result of results) {
+    if (!result.prunable) continue;
+    const replacement = replacementsById.get(result.entryId);
+    if (!replacement) continue;
+    replacements.set(result.toolCallId, replacement);
+  }
+
+  return { replacements, resultEntryIds: new Set(results.map((result) => result.entryId)) };
+}

package/src/optimizers/deduplicator/types.ts

@@ -0,0 +1,14 @@
+import type { Range } from "../inspector/types.js";
+
+export interface DeduplicatorState {
+  replacements: Map<string, string[]>;
+  resultEntryIds: Set<string>;
+}
+
+export interface ResourceResult {
+  entryId: string;
+  range: Range;
+  resource: string;
+  toolCallId: string;
+  prunable: boolean;
+}

package/src/optimizers/entries.ts

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { isRecord } from "../utils.js";
+
+export function readSessionEntries(
+  sessionFile: string | undefined,
+): Record<string, unknown>[] | undefined {
+  if (!sessionFile || !existsSync(sessionFile)) return;
+
+  try {
+    const sessionText = readFileSync(sessionFile, "utf8");
+    const entries: Record<string, unknown>[] = [];
+    for (const line of sessionText.split("\n")) {
+      if (line.trim().length === 0) continue;
+      const entry = JSON.parse(line);
+      if (!isRecord(entry)) return;
+      entries.push(entry);
+    }
+    return entries;
+  } catch {
+    return;
+  }
+}
+
+export function writeSessionEntries(sessionFile: string, entries: Record<string, unknown>[]) {
+  const temporaryFile = `${sessionFile}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(
+      temporaryFile,
+      `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`,
+      "utf8",
+    );
+    renameSync(temporaryFile, sessionFile);
+  } finally {
+    if (existsSync(temporaryFile)) unlinkSync(temporaryFile);
+  }
+}
+
+export function getEntryId(entry: Record<string, unknown>): string | undefined {
+  const entryId = entry.id;
+  if (typeof entryId !== "string" || entryId.length === 0) return;
+  return entryId;
+}
+
+export function getMessage(entry: Record<string, unknown>): Record<string, unknown> | undefined {
+  if (entry.type !== "message") return;
+  const message = entry.message;
+  if (!isRecord(message)) return;
+  return message;
+}
+
+export function getToolResultMessage(
+  entry: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  const message = getMessage(entry);
+  if (!message || message.role !== "toolResult") return;
+  if (typeof message.toolCallId !== "string" || message.toolCallId.length === 0) return;
+  if (typeof message.toolName !== "string" || message.toolName.length === 0) return;
+  return message;
+}
+
+export function getDetails(message: Record<string, unknown>): Record<string, unknown> | undefined {
+  const details = message.details;
+  if (!isRecord(details)) return;
+  return details;
+}
+
+export function getParentId(entry: Record<string, unknown>): string | null {
+  if (typeof entry.parentId === "string") return entry.parentId;
+  return null;
+}
+
+export function getBranchEntries(
+  entries: Record<string, unknown>[],
+  leafId: string | null,
+): Record<string, unknown>[] {
+  if (!leafId) return [];
+
+  const entriesById = new Map<string, Record<string, unknown>>();
+  for (const entry of entries) {
+    const entryId = getEntryId(entry);
+    if (entryId) entriesById.set(entryId, entry);
+  }
+  if (!entriesById.has(leafId)) return [];
+
+  const branch: Record<string, unknown>[] = [];
+  const visitedIds = new Set<string>();
+  let currentId: string | null = leafId;
+  while (currentId && !visitedIds.has(currentId)) {
+    const entry = entriesById.get(currentId);
+    if (!entry) break;
+    visitedIds.add(currentId);
+    branch.push(entry);
+    currentId = getParentId(entry);
+  }
+  return branch.reverse();
+}
+
+export function getLastEntryId(entries: Record<string, unknown>[]): string | null {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entryId = getEntryId(entries[index]!);
+    if (entryId) return entryId;
+  }
+  return null;
+}

package/src/optimizers/index.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import deduplicator from "./deduplicator/index.js";
+import compactor from "./compactor/index.js";
+import codeMap from "./mapper/index.js";
+import inspect from "./inspector/index.js";
+import languages from "./languages/index.js";
+import pruner from "./pruner/index.js";
+
+export default function (pi: ExtensionAPI) {
+  compactor(pi);
+  languages(pi);
+  deduplicator(pi);
+  pruner(pi);
+
+  pi.registerTool(codeMap);
+  pi.registerTool(inspect);
+}

package/src/optimizers/inspector/helpers.ts

@@ -0,0 +1,60 @@
+import type { InspectToolDetails } from "./types.js";
+
+export function parseInspectToolDetails(inspected: unknown) {
+  if (!inspected || typeof inspected !== "object") return;
+
+  const path = (inspected as { path?: unknown }).path;
+  const symbol = (inspected as { symbol?: unknown }).symbol;
+  const range = (inspected as { range?: unknown }).range;
+
+  if (typeof path !== "string" || path.length === 0) return;
+  if (typeof symbol !== "string" || symbol.length === 0) return;
+  if (!Array.isArray(range) || range.length !== 2) return;
+
+  const start = range[0];
+  const end = range[1];
+  if (
+    typeof start !== "number" ||
+    typeof end !== "number" ||
+    !Number.isInteger(start) ||
+    !Number.isInteger(end) ||
+    start < 1 ||
+    end < start
+  ) {
+    return;
+  }
+
+  return { path, symbol, range: [start, end] } satisfies InspectToolDetails;
+}
+
+export function pruneInspectResults(messages: Array<{ role?: string }>) {
+  const seen = new Set<string>();
+  let changed = false;
+
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index] as {
+      role: string;
+      toolName?: string;
+      details?: unknown;
+      isError?: boolean;
+    };
+
+    if (message.role !== "toolResult" || message.toolName !== "inspect" || message.isError) {
+      continue;
+    }
+
+    const details = parseInspectToolDetails(message.details);
+    if (!details) continue;
+
+    const symbolKey = `${details.path}#${details.symbol}`;
+    if (!seen.has(symbolKey)) {
+      seen.add(symbolKey);
+      continue;
+    }
+
+    changed = true;
+    messages.splice(index, 1);
+  }
+
+  return changed;
+}

package/src/optimizers/inspector/index.ts

@@ -0,0 +1,89 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { inspectSymbol } from "./inspect.js";
+import type { InspectToolDetails } from "./types.js";
+
+const inspect = defineTool({
+  name: "inspect",
+  label: "Inspect",
+  description: "Fetch one symbol's full body from one file. Output is safe for targeted edits.",
+  parameters: Type.Object({
+    path: Type.String({
+      description: "Exact file path containing target symbol (relative to cwd or absolute)",
+    }),
+    symbol: Type.String({
+      description:
+        "Exact symbol string for one declaration in file: function name, class name, method name (MyClass.method), synthetic anonymous name (anonymous~1), or duplicate form name~2",
+    }),
+  }),
+  async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+    const path = params.path.trim().replaceAll("\\", "/");
+    const symbol = params.symbol.trim();
+
+    if (path.length === 0 || symbol.length === 0 || symbol.includes("#")) {
+      return {
+        isError: false,
+        details: null,
+        content: [
+          {
+            type: "text",
+            text: "inspect symbol format invalid. path/symbol must be non-empty; symbol cannot include '#'. use symbol name, e.g. name or name~2",
+          },
+        ],
+      };
+    }
+
+    try {
+      const inspected = await inspectSymbol(ctx.cwd, path, symbol, signal);
+      if (!inspected) {
+        return {
+          isError: false,
+          details: null,
+          content: [
+            {
+              type: "text",
+              text: "inspect symbol not found. verify path/symbol; for duplicates use ~n suffix (name~2). then try container symbol. if still missing, run code_map with broader kinds",
+            },
+          ],
+        };
+      }
+
+      const details = {
+        path: inspected.path,
+        symbol: inspected.symbol,
+        range: inspected.range,
+      } satisfies InspectToolDetails;
+
+      return { isError: false, details, content: [{ type: "text", text: inspected.text }] };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        isError: true,
+        details: null,
+        content: [{ type: "text", text: `inspect failed: ${message}` }],
+      };
+    }
+  },
+  renderCall(args, theme) {
+    return new Text(
+      `${theme.fg("toolTitle", "inspect")} ${theme.underline(theme.fg("accent", args.path))} ${theme.fg("warning", args.symbol)}`,
+      0,
+      0,
+    );
+  },
+  renderResult(result, { expanded }, theme, context) {
+    if (!expanded && !context.isError) {
+      return new Text("", 0, 0);
+    }
+
+    const output = result.content[0];
+    return new Text(
+      `\n${output?.type === "text" ? theme.fg("toolOutput", output.text) : ""}`,
+      0,
+      0,
+    );
+  },
+});
+
+export default inspect;

package/src/optimizers/inspector/inspect.ts

@@ -0,0 +1,88 @@
+import type { SyntaxNode } from "tree-sitter";
+import type { LanguageSymbol } from "../languages/index.js";
+import { collectSymbols, SYMBOL_KINDS } from "../languages/index.js";
+import type { Range } from "./types.js";
+
+function inspectGroupedSymbols(
+  path: string,
+  symbolName: string,
+  symbols: LanguageSymbol[],
+): { path: string; symbol: string; range: Range; text: string } | undefined {
+  const groupedSymbolsMatch = /^(imports|exports)~([1-9]\d*)$/.exec(symbolName);
+  if (!groupedSymbolsMatch) return;
+
+  const groupedSymbolKind = groupedSymbolsMatch[1] === "imports" ? "deps" : "public";
+  const requestedGroup = Number(groupedSymbolsMatch[2]);
+  const groupedNodes: SyntaxNode[] = [];
+  const groupedRanges = new Set<string>();
+  let symbolsCollapsed = false;
+  let symbolsGroupIndex = 0;
+
+  for (const symbol of symbols) {
+    if (symbol.kind !== groupedSymbolKind) {
+      symbolsCollapsed = false;
+      continue;
+    }
+    if (!symbolsCollapsed) {
+      symbolsCollapsed = true;
+      symbolsGroupIndex += 1;
+    }
+    if (symbolsGroupIndex !== requestedGroup) continue;
+
+    let groupedNode = symbol.node;
+    if (groupedSymbolKind === "deps") {
+      while (groupedNode.parent?.parent) {
+        groupedNode = groupedNode.parent;
+      }
+    }
+
+    const groupedRange = `${groupedNode.startIndex}-${groupedNode.endIndex}`;
+    if (groupedRanges.has(groupedRange)) continue;
+
+    groupedRanges.add(groupedRange);
+    groupedNodes.push(groupedNode);
+  }
+
+  const firstNode = groupedNodes[0];
+  const lastNode = groupedNodes[groupedNodes.length - 1];
+  if (!firstNode || !lastNode) return;
+  return {
+    path,
+    symbol: symbolName,
+    text: groupedNodes.map((groupedNode) => groupedNode.text).join("\n"),
+    range: [
+      firstNode.startPosition.row + 1,
+      lastNode.endPosition.row + (lastNode.endPosition.column > 0 ? 1 : 0),
+    ],
+  };
+}
+
+export async function inspectSymbol(
+  cwd: string,
+  path: string,
+  symbolName: string,
+  signal?: AbortSignal,
+): Promise<{ path: string; symbol: string; range: Range; text: string } | undefined> {
+  if (signal?.aborted) {
+    throw new Error("inspector aborted");
+  }
+  const kinds = new Set(SYMBOL_KINDS);
+  const symbols = await collectSymbols(cwd, path, kinds);
+
+  const inspectedGroup = inspectGroupedSymbols(path, symbolName, symbols);
+  if (inspectedGroup) return inspectedGroup;
+
+  for (const symbol of symbols) {
+    if (symbol.name !== symbolName) continue;
+
+    return {
+      path: symbol.path,
+      symbol: symbol.name,
+      range: [
+        symbol.node.startPosition.row + 1,
+        symbol.node.endPosition.row + (symbol.node.endPosition.column > 0 ? 1 : 0),
+      ],
+      text: symbol.node.text,
+    };
+  }
+}

package/src/optimizers/inspector/types.ts

@@ -0,0 +1,7 @@
+export type Range = [number, number];
+
+export interface InspectToolDetails {
+  path: string;
+  symbol: string;
+  range: Range;
+}

package/src/optimizers/languages/go.ts

@@ -0,0 +1,79 @@
+import type { Language, SyntaxNode } from "tree-sitter";
+import { loadGrammarModule } from "./grammar.js";
+import { RuleBasedLanguageProfile, type SymbolKindRule } from "./types.js";
+
+export class GoLanguageProfile extends RuleBasedLanguageProfile {
+  constructor() {
+    super(
+      new Set([".go"]),
+      { __default__: "name" },
+      new Set(["source_file"]),
+      new Set([
+        "const_declaration",
+        "import_declaration",
+        "import_spec_list",
+        "type_declaration",
+        "var_declaration",
+        "var_spec_list",
+      ]),
+      new Map<string, SymbolKindRule[]>([
+        ["function_declaration", [{ kind: "func", topLevelOnly: true }]],
+        ["method_declaration", [{ kind: "method" }]],
+        ["method_elem", [{ kind: "method", parent: "interface_type", container: "type_spec" }]],
+        ["const_spec", [{ kind: "decl", topLevelOnly: true }]],
+        ["import_spec", [{ kind: "deps", topLevelOnly: true }]],
+        ["type_alias", [{ kind: "class", topLevelOnly: true }]],
+        ["type_spec", [{ kind: "class", topLevelOnly: true }]],
+        ["var_spec", [{ kind: "decl", topLevelOnly: true }]],
+      ]),
+    );
+  }
+
+  async loadLanguage(_extension: string) {
+    const languagePack = await loadGrammarModule("tree-sitter-go");
+    const languageExport = (languagePack.default ?? languagePack) as Language;
+    return languageExport;
+  }
+
+  readNodeName(node: SyntaxNode) {
+    if (node.type === "import_spec") {
+      const importName = this.readFieldText(node, "name");
+      if (importName) {
+        return importName;
+      }
+
+      const importPath = this.readFieldText(node, "path");
+      if (importPath) {
+        return importPath.replace(/^("|')(.*)\1$/, "$2");
+      }
+    }
+
+    const nodeName = this.readNameField(node);
+    if (nodeName) {
+      return nodeName;
+    }
+
+    if (
+      node.type === "field_identifier" ||
+      node.type === "identifier" ||
+      node.type === "package_identifier" ||
+      node.type === "type_identifier"
+    ) {
+      return this.readNodeText(node);
+    }
+  }
+
+  readContainerName(node: SyntaxNode) {
+    if (node.type === "method_declaration") {
+      const receiverNode = node.childForFieldName("receiver");
+      const receiverParameterNode = receiverNode?.namedChild(0);
+      const receiverTypeNode = receiverParameterNode?.childForFieldName("type");
+      const receiverType = this.readNodeText(receiverTypeNode);
+      if (receiverType) {
+        return receiverType.replace(/^\*+/, "");
+      }
+    }
+
+    return super.readContainerName(node);
+  }
+}