ashlr-plugin 1.36.4

package/servers/_summarize.ts

@@ -0,0 +1,208 @@
+/**
+ * Shared LLM summarization helper for ashlr MCP tools.
+ *
+ * Replaces dumb truncation with smart summarization for the cases where
+ * the middle of a large output actually matters (large source files, big
+ * diffs, log tails with errors buried mid-stream, etc.).
+ *
+ * Architecture (v1.22 Track D — LLM Hybrid Strategy)
+ * - Provider hierarchy: Anthropic Haiku 4.5 → ONNX (stubbed) → Local LM Studio → snipCompact
+ * - ASHLR_LLM_PROVIDER controls selection: "auto" (default) | "anthropic" | "onnx" | "local" | "off"
+ * - "auto" tries Anthropic first (ANTHROPIC_API_KEY or ~/.claude/.credentials.json),
+ *   then ONNX (when bundled), then local LM Studio at ASHLR_LLM_URL
+ * - SHA-256 cache at ~/.ashlr/summary-cache/<hash>.txt (1h TTL)
+ * - Always appends a one-line hint so the agent knows it can ask for the
+ *   full output via bypassSummary:true
+ *
+ * Public API: summarizeIfLarge() — re-exported from ./_llm-providers/index.ts.
+ * All callers import from this file; internal implementation lives in
+ * ./_llm-providers/ to keep concerns separated.
+ */
+
+// ---------------------------------------------------------------------------
+// Confidence badge — pure helper, no I/O
+// ---------------------------------------------------------------------------
+
+export interface ConfidenceBadgeOpts {
+  /** Tool name for the escalation hint (e.g. "ashlr__read"). */
+  toolName: string;
+  /** Raw bytes before compression. */
+  rawBytes: number;
+  /** Output bytes after compression. */
+  outputBytes: number;
+  /** True if the LLM fell back to truncation. Always → low tier. */
+  fellBack?: boolean;
+  /** True if the command exited non-zero AND bytes were elided. Always → low. */
+  nonZeroExit?: boolean;
+  /** Optional extra tag appended before the closing bracket (e.g. "mtime=123"). */
+  extra?: string;
+}
+
+type ConfidenceTier = "high" | "medium" | "low";
+
+function _tier(opts: ConfidenceBadgeOpts): ConfidenceTier {
+  if (opts.fellBack || opts.nonZeroExit) return "low";
+  // Nothing to compress → trivially "high" (no information lost).
+  if (opts.rawBytes <= 0) return "high";
+  // Everything was elided — the exact opposite of high confidence.
+  if (opts.outputBytes <= 0) return "low";
+  const ratio = opts.outputBytes / opts.rawBytes;
+  if (ratio >= 1 / 3) return "high";
+  if (ratio >= 1 / 8) return "medium";
+  return "low";
+}
+
+/** Exposed so call sites can branch on tier (e.g. to emit a logEvent). */
+export function confidenceTier(opts: ConfidenceBadgeOpts): ConfidenceTier {
+  return _tier(opts);
+}
+
+/**
+ * Return a one-line confidence footer to append to compressed tool output.
+ * Returns an empty string when no compression occurred (rawBytes ≤ outputBytes)
+ * so call sites can always do `text + confidenceBadge(...)` safely.
+ *
+ * The returned string (when non-empty) is ≤ 80 chars and starts with "\n".
+ */
+export function confidenceBadge(opts: ConfidenceBadgeOpts): string {
+  // No compression and no failure signal → no badge. Also skip when the
+  // raw payload is tiny — a badge on a sub-512-byte response is more noise
+  // than signal. fellBack/nonZeroExit still emit (they're load-bearing
+  // quality signals regardless of payload size).
+  if (!opts.fellBack && !opts.nonZeroExit) {
+    if (opts.rawBytes <= opts.outputBytes) return "";
+    if (opts.rawBytes < 512) return "";
+  }
+
+  const tier = _tier(opts);
+  const rawKB = (opts.rawBytes / 1024).toFixed(0) + "KB";
+  const outKB = (opts.outputBytes / 1024).toFixed(0) + "KB";
+  const extraPart = opts.extra ? ` · ${opts.extra}` : "";
+
+  // 80-char budget. Required pieces (always included): tier name + the
+  // actionable `bypassSummary:true` hint. Optional pieces dropped under
+  // pressure in order: (1) byte numbers, (2) the hint wording shortens.
+  // `extra` (when caller passes one) is treated as required — it's how
+  // callers thread debug context (e.g. mtime) into the badge.
+  const BUDGET = 80;
+  const hint = tier === "low"
+    ? "bypassSummary:true to recover fidelity"
+    : "bypassSummary:true recovers fidelity";
+
+  const withBytes = `[ashlr confidence: ${tier} · ${rawKB}→${outKB}${extraPart} · ${hint}]`;
+  const withoutBytes = `[ashlr confidence: ${tier}${extraPart} · ${hint}]`;
+  const minimal = `[ashlr confidence: ${tier} · ${hint}]`;
+
+  let line = withBytes;
+  if (line.length > BUDGET) line = withoutBytes;
+  if (line.length > BUDGET) line = minimal;
+  if (line.length > BUDGET) line = line.slice(0, BUDGET - 1) + "]";
+
+  return "\n" + line;
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_THRESHOLD_BYTES = 16_384;
+
+// ---------------------------------------------------------------------------
+// Public API — re-exported from provider abstraction layer
+// ---------------------------------------------------------------------------
+
+export type { SummarizeOpts, SummarizeResult } from "./_llm-providers/index.ts";
+export { summarizeIfLarge } from "./_llm-providers/index.ts";
+
+
+// ---------------------------------------------------------------------------
+// Per-tool prompts (exported so wiring code references them by name, not by string)
+// ---------------------------------------------------------------------------
+
+export const PROMPTS = {
+  read:
+    "You are summarizing a source code file for an AI coding agent. Output ≤500 chars. " +
+    "Preserve: file purpose (1 sentence), key functions/classes (1 line each with line ranges). " +
+    "Preserve VERBATIM with line numbers: every @-prefixed decorator or annotation (@deprecated, " +
+    "@Injectable, @staticmethod, etc.) with its associated symbol; every " +
+    "TODO|FIXME|XXX|HACK|WARNING|THREAD-UNSAFE|DEPRECATED|NOTE|SAFETY marker; " +
+    "every top-level export/module.exports/__all__ statement (symbol name only, not body). " +
+    "Output as plain text — no markdown headers.",
+
+  diff:
+    "You are summarizing a git diff for an AI coding agent. Output ≤500 chars. " +
+    "Preserve: changed file paths (each on its own line with +adds/-dels), refactor signatures " +
+    "(X→Y renames, signature changes), breaking changes (interface/export changes), " +
+    "test-coverage shifts. Preserve hunk headers like '@@ -45,6 +45,14 @@' verbatim where they exist. " +
+    "Skip pure-formatting changes. Output as plain text.",
+
+  logs:
+    "You are extracting signal from a log file for a debugging agent. Output ≤600 chars. " +
+    "Preserve VERBATIM: the first error and its full stack trace, the most recent error and its trace, " +
+    "any 'caused by' chains. Summarize: count of errors/warnings by category, " +
+    "deduplicated repetition patterns ('connection timeout x47'), notable preceding warnings. " +
+    "Output as plain text. Do not invent context that isn't in the logs.",
+
+  grep:
+    "You are summarizing grep results for a code-navigation agent. Output ≤400 chars. " +
+    "Preserve VERBATIM: the top 3 matches with full file:line:content. " +
+    "Summarize: total matches, file distribution (which files have the most), dominant pattern type. " +
+    "Output as plain text — keep file paths fully qualified.",
+
+  bash:
+    "You are summarizing shell command output for an AI agent. Output ≤500 chars. " +
+    "Preserve VERBATIM: errors with full stack traces, the final result line " +
+    "(e.g. '187 passed', 'Build failed', exit code), key counts/identifiers. " +
+    "Summarize: progress phases (compile → test → build), warnings by category. " +
+    "Output as plain text. Do not embellish.",
+
+  sql:
+    "You are summarizing a SQL query result for a data-exploration agent. Output ≤400 chars. " +
+    "Preserve VERBATIM: the first 3 and last 2 rows. " +
+    "Summarize: total row count, column types, dominant values per column (e.g. 'status: 80% active, 15% pending'), " +
+    "notable outliers (max, min, NULL counts). Output as plain text — keep numbers exact.",
+
+  webfetch:
+    "You are summarizing a fetched web page for an AI coding agent. Output ≤500 chars. " +
+    "Preserve VERBATIM: the page title, all headings (as '# Heading' / '## Sub'), the first paragraph, " +
+    "all hyperlinks with anchor text and URL (format: 'text (url)'), any error or warning messages. " +
+    "Summarize: the main topic, key findings or data points, and any actionable content. " +
+    "Omit boilerplate, nav menus, cookie notices, and marketing copy. Output as plain text.",
+
+  http:
+    "You are summarizing an HTTP response for an AI coding agent. Output ≤500 chars. " +
+    "Preserve VERBATIM: status code, content-type, all headings, the first paragraph, key data fields " +
+    "(especially IDs, URLs, error codes, and counts), all hyperlinks. " +
+    "For JSON: preserve top-level keys, the first 3 array items verbatim, and total array lengths. " +
+    "For HTML: same rules as webfetch — title, headings, first paragraph, links. " +
+    "Omit boilerplate, nav, and cookie notices. Output as plain text.",
+
+  glob:
+    "You are summarizing a file glob result for an AI coding agent. Output ≤400 chars. " +
+    "Preserve VERBATIM: the top 5 matching paths. " +
+    "Summarize: total match count, top-level directory distribution with counts (e.g. 'src/: 42, tests/: 18'), " +
+    "any non-obvious structural cues (e.g. nested package layout, monorepo roots). " +
+    "Output as plain text — keep file paths fully qualified.",
+
+  tree:
+    "You are summarizing a project directory tree for an AI coding agent. Output ≤400 chars. " +
+    "Preserve VERBATIM: the top-level directory names and their immediate children counts. " +
+    "Summarize: total dirs and files, dominant file types by extension with counts, " +
+    "any non-obvious structural cues (e.g. monorepo packages/, multiple entry points, config clusters). " +
+    "Output as plain text — no markdown headers.",
+
+  diff_semantic:
+    "You are summarizing an AST-aware semantic diff for an AI coding agent. Output ≤500 chars. " +
+    "Preserve VERBATIM: every detected rename row (old→new), signature-only change rows " +
+    "(file:line: old-sig → new-sig), and the final counts header line. " +
+    "Summarize: the total files touched, dominant change category (rename | signature | format | mixed), " +
+    "whether any breaking-surface (exported symbol) changed. Drop pure-formatting chatter. " +
+    "Output as plain text — no markdown headers.",
+
+  genome_synthesize:
+    "You are consolidating N raw auto-observations about a codebase into a short, curated genome section. Output rules:\n\n" +
+    "- If the observations contain NO novel insight (all are restatements of things the genome likely already records — library names, file paths without context, generic boilerplate), output EXACTLY this single line:\n" +
+    "  {\"novel\": false, \"reason\": \"<one sentence why>\"}\n\n" +
+    "- Otherwise output 1-3 bullet points, each ≤ 200 chars, in plain markdown (no header, no fences). Each bullet must be a genuine insight tied to a concrete file, symbol, decision, or invariant. Deduplicate — if two observations say the same thing, merge them. Skip observations that are pure noise (tool output dumps, test names, generic changelog chatter).\n\n" +
+    "- No prose preamble. No 'Here are the bullets:'. Just the bullets (or the novel:false sentinel).",
+} as const;

package/servers/_task-graph-render.ts

@@ -0,0 +1,217 @@
+/**
+ * _task-graph-render.ts — Track B rich renderer for the orchestration DAG.
+ *
+ * Renders a TaskGraph as a numbered topological tree with per-node agent kind,
+ * token budget, scope truncation, and dep markers. The slash command + tests
+ * assert against the output; the CLI prints it ahead of the y/n/e confirm.
+ *
+ * Public surface (stable contract with Track C):
+ *
+ *   renderTaskGraph(g: TaskGraph, opts?: RenderOptions): string
+ *
+ * Guarantees:
+ *   - Never throws. Falls back to a plain-text dump if anything goes sideways.
+ *   - Deterministic: stable topo order (input order is a tiebreaker).
+ *   - Color OFF by default — keeps test goldens stable.
+ *   - Empty graph → "Orchestration plan — empty graph (0 nodes)".
+ *   - Single node → no "depends on" markers.
+ */
+
+import type { TaskGraph, TaskNode } from "./_task-graph.ts";
+
+export interface RenderOptions {
+  /** Enable ANSI color sequences (default: false for deterministic tests). */
+  color?: boolean;
+  /** Truncate per-node scope listings beyond this many entries (default: 5). */
+  maxScopeFiles?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function renderTaskGraph(g: TaskGraph, opts: RenderOptions = {}): string {
+  try {
+    return doRender(g, opts);
+  } catch {
+    // Renderer must NEVER throw — fall back to a plain-text dump that callers
+    // can still display while we investigate the failure mode.
+    return safeFallback(g);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+function doRender(g: TaskGraph, opts: RenderOptions): string {
+  const maxScope = Number.isFinite(opts.maxScopeFiles) && (opts.maxScopeFiles as number) >= 0
+    ? Math.floor(opts.maxScopeFiles as number)
+    : 5;
+  const useColor = opts.color === true;
+
+  const bold = (s: string): string => (useColor ? `\x1b[1m${s}\x1b[0m` : s);
+  const dim  = (s: string): string => (useColor ? `\x1b[2m${s}\x1b[0m` : s);
+  const cyan = (s: string): string => (useColor ? `\x1b[36m${s}\x1b[0m` : s);
+
+  const lines: string[] = [];
+
+  // Empty graph — short-circuit before topo sort.
+  if (!g.nodes || g.nodes.length === 0) {
+    lines.push(bold(`Orchestration plan`) + ` — empty graph (0 nodes)`);
+    if (g.goal) lines.push(`  goal: ${quote(g.goal)}`);
+    if (g.scope) lines.push(`  scope: ${g.scope}`);
+    return lines.join("\n");
+  }
+
+  // -- Header -----------------------------------------------------------------
+  const nodeCount = g.nodes.length;
+  const budget = typeof g.metadata?.totalTokenBudget === "number"
+    ? g.metadata.totalTokenBudget
+    : g.nodes.reduce((s, n) => s + (Number.isFinite(n.estimatedTokens) ? n.estimatedTokens : 0), 0);
+
+  lines.push(`${bold("Orchestration plan")} — goal: ${quote(g.goal ?? "")}`);
+  if (g.scope) lines.push(`scope: ${g.scope}`);
+  lines.push(
+    `tier: ${g.tier} · ${nodeCount} ${nodeCount === 1 ? "node" : "nodes"} · ~${formatTokens(budget)} token budget`,
+  );
+
+  // -- Topological order ------------------------------------------------------
+  const ordered = topoSort(g.nodes);
+  const positionById = new Map<string, number>();
+  ordered.forEach((n, i) => positionById.set(n.id, i + 1));
+
+  for (let i = 0; i < ordered.length; i++) {
+    const n = ordered[i]!;
+    lines.push(""); // blank line between nodes
+    const idx = i + 1;
+    const tok = formatTokens(Number.isFinite(n.estimatedTokens) ? n.estimatedTokens : 0);
+    const head = `[${idx}] ${bold(n.id)} (${n.agentKind} · ~${tok} tok)`;
+
+    // Dep marker — only meaningful when there are deps AND >1 node.
+    const deps = Array.isArray(n.deps) ? n.deps : [];
+    let depSuffix = "";
+    if (nodeCount > 1 && deps.length > 0) {
+      const positions = deps
+        .map((d) => positionById.get(d))
+        .filter((p): p is number => typeof p === "number")
+        .sort((a, b) => a - b);
+      if (positions.length > 0) {
+        const tag = positions.map((p) => `[${p}]`).join(", ");
+        depSuffix = `  ${cyan("⤴")} ${dim(`depends on ${tag}`)}`;
+      }
+    }
+    lines.push(head + depSuffix);
+
+    // Goal line.
+    lines.push(`    ├─ goal: ${n.goal}`);
+
+    // Scope line — truncate at maxScope.
+    const scope = Array.isArray(n.scope) ? n.scope : [];
+    if (scope.length > 0) {
+      const shown = scope.slice(0, maxScope);
+      const more = scope.length - shown.length;
+      const suffix = more > 0 ? ` (+${more} more)` : "";
+      lines.push(`    ├─ scope: ${shown.join(", ")}${suffix}`);
+    } else {
+      lines.push(`    ├─ scope: (none)`);
+    }
+
+    // Deps line — explicit list (or "none") at the bottom for clarity.
+    if (deps.length === 0) {
+      lines.push(`    └─ deps: none`);
+    } else {
+      lines.push(`    └─ deps: ${deps.join(", ")}`);
+    }
+  }
+
+  lines.push("");
+  lines.push(dim("Press y to execute, n to cancel, e to edit YAML."));
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Topological sort — Kahn's algorithm with stable input-order tiebreaker.
+// ---------------------------------------------------------------------------
+
+function topoSort(nodes: readonly TaskNode[]): TaskNode[] {
+  const byId = new Map<string, TaskNode>();
+  const indegree = new Map<string, number>();
+  const inputOrder = new Map<string, number>();
+
+  nodes.forEach((n, i) => {
+    byId.set(n.id, n);
+    inputOrder.set(n.id, i);
+    if (!indegree.has(n.id)) indegree.set(n.id, 0);
+  });
+
+  // Build adjacency list + indegrees from deps (deps point INTO a node).
+  const successors = new Map<string, string[]>();
+  for (const n of nodes) {
+    const deps = Array.isArray(n.deps) ? n.deps : [];
+    indegree.set(n.id, deps.filter((d) => byId.has(d)).length);
+    for (const d of deps) {
+      if (!byId.has(d)) continue;
+      const list = successors.get(d) ?? [];
+      list.push(n.id);
+      successors.set(d, list);
+    }
+  }
+
+  const ready: string[] = [];
+  for (const [id, deg] of indegree) if (deg === 0) ready.push(id);
+  ready.sort((a, b) => (inputOrder.get(a) ?? 0) - (inputOrder.get(b) ?? 0));
+
+  const out: TaskNode[] = [];
+  const visited = new Set<string>();
+
+  while (ready.length > 0) {
+    const id = ready.shift()!;
+    if (visited.has(id)) continue;
+    visited.add(id);
+    const n = byId.get(id);
+    if (n) out.push(n);
+    for (const s of successors.get(id) ?? []) {
+      const prev = indegree.get(s) ?? 0;
+      const next = prev - 1;
+      indegree.set(s, next);
+      if (next === 0 && !visited.has(s)) ready.push(s);
+    }
+    ready.sort((a, b) => (inputOrder.get(a) ?? 0) - (inputOrder.get(b) ?? 0));
+  }
+
+  // Cycle fallback — validator should have rejected this, but be defensive.
+  if (out.length < nodes.length) {
+    for (const n of nodes) if (!visited.has(n.id)) out.push(n);
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatTokens(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return "0";
+  if (n < 1000) return String(Math.floor(n));
+  // Round to nearest hundred so we get e.g. ~5,200 not ~5,237.
+  const rounded = Math.round(n / 100) * 100;
+  return rounded.toLocaleString("en-US");
+}
+
+function quote(s: string): string {
+  return `"${s}"`;
+}
+
+function safeFallback(g: TaskGraph | null | undefined): string {
+  try {
+    const head = `Orchestration plan — goal: "${(g?.goal ?? "").toString()}"`;
+    const count = Array.isArray(g?.nodes) ? g!.nodes.length : 0;
+    const ids = Array.isArray(g?.nodes) ? g!.nodes.map((n) => String(n?.id ?? "?")).join(", ") : "";
+    return `${head}\nnodes: ${count}${ids ? ` (${ids})` : ""}`;
+  } catch {
+    return "Orchestration plan — render fallback";
+  }
+}