|
| 1 | +/** |
| 2 | + * tool-call-formatter.ts — Human-readable tool call summaries. |
| 3 | + * |
| 4 | + * Formats SDL-MCP tool calls and results as concise text for user-facing |
| 5 | + * MCP logging notifications. The JSON response remains unchanged for the LLM. |
| 6 | + */ |
| 7 | + |
| 8 | +// --------------------------------------------------------------------------- |
| 9 | +// Helpers |
| 10 | +// --------------------------------------------------------------------------- |
| 11 | + |
| 12 | +function truncName(s: string, max = 40): string { |
| 13 | + return s.length > max ? s.slice(0, max - 1) + "…" : s; |
| 14 | +} |
| 15 | + |
| 16 | +function shortPath(p: string): string { |
| 17 | + // Keep last 2 path segments for brevity |
| 18 | + const parts = p.replace(/\\/g, "/").split("/"); |
| 19 | + return parts.length <= 2 ? p : "…/" + parts.slice(-2).join("/"); |
| 20 | +} |
| 21 | + |
| 22 | +function tok(n: number): string { |
| 23 | + if (n < 1000) return String(n); |
| 24 | + if (n < 1_000_000) return (n / 1000).toFixed(1) + "k"; |
| 25 | + return (n / 1_000_000).toFixed(2) + "M"; |
| 26 | +} |
| 27 | + |
| 28 | +function rng(r: { startLine?: number; endLine?: number } | undefined): string { |
| 29 | + if (!r) return ""; |
| 30 | + return `L${r.startLine ?? "?"}–${r.endLine ?? "?"}`; |
| 31 | +} |
| 32 | + |
| 33 | +function str(v: unknown): string { |
| 34 | + return typeof v === "string" ? v : ""; |
| 35 | +} |
| 36 | + |
| 37 | +function num(v: unknown): number { |
| 38 | + return typeof v === "number" ? v : 0; |
| 39 | +} |
| 40 | + |
| 41 | +// --------------------------------------------------------------------------- |
| 42 | +// Per-tool formatters |
| 43 | +// --------------------------------------------------------------------------- |
| 44 | + |
| 45 | +type Formatter = ( |
| 46 | + args: Record<string, unknown>, |
| 47 | + res: Record<string, unknown>, |
| 48 | +) => string | null; |
| 49 | + |
| 50 | +function fmtSymbolSearch(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 51 | + const results = r.results as Array<Record<string, unknown>> | undefined; |
| 52 | + if (!results) return null; |
| 53 | + const q = str(_a.query); |
| 54 | + const lines = [`symbol.search "${q}" → ${results.length} result${results.length !== 1 ? "s" : ""}`]; |
| 55 | + for (const s of results.slice(0, 5)) { |
| 56 | + const name = str(s.name).padEnd(24); |
| 57 | + const kind = str(s.kind).padEnd(10); |
| 58 | + lines.push(` ${name} ${kind} ${shortPath(str(s.file))}`); |
| 59 | + } |
| 60 | + if (results.length > 5) lines.push(` …and ${results.length - 5} more`); |
| 61 | + return lines.join("\n"); |
| 62 | +} |
| 63 | + |
| 64 | +function fmtSymbolGetCard(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 65 | + const card = r.card as Record<string, unknown> | undefined; |
| 66 | + if (r.notModified) return `symbol.getCard → not modified (ETag hit)`; |
| 67 | + if (!card) return null; |
| 68 | + const deps = card.deps as Record<string, unknown[]> | undefined; |
| 69 | + const imports = deps?.imports?.length ?? 0; |
| 70 | + const calls = deps?.calls?.length ?? 0; |
| 71 | + return `symbol.getCard → ${str(card.name)} (${str(card.kind)})\n File: ${shortPath(str(card.file))} ${rng(card.range as any)}\n Deps: ${imports} imports, ${calls} calls`; |
| 72 | +} |
| 73 | + |
| 74 | +function fmtSymbolGetCards(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 75 | + const cards = r.cards as Array<Record<string, unknown>> | undefined; |
| 76 | + if (!cards) return null; |
| 77 | + return `symbol.getCards → ${cards.length} card${cards.length !== 1 ? "s" : ""}`; |
| 78 | +} |
| 79 | + |
| 80 | +function fmtCodeSkeleton(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 81 | + const file = str(r.file); |
| 82 | + const orig = num(r.originalLines); |
| 83 | + const est = num(r.estimatedTokens); |
| 84 | + const trunc = r.truncated ? " (truncated)" : ""; |
| 85 | + return `code.getSkeleton → ${shortPath(file)}\n ${orig} → skeleton ${rng(r.range as any)}${trunc} (~${tok(est)} tokens)`; |
| 86 | +} |
| 87 | + |
| 88 | +function fmtCodeHotPath(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 89 | + const matched = r.matchedIdentifiers as string[] | undefined; |
| 90 | + const requested = (_a.identifiersToFind as string[])?.length ?? 0; |
| 91 | + const found = matched?.length ?? 0; |
| 92 | + const trunc = r.truncated ? " (truncated)" : ""; |
| 93 | + return `code.getHotPath → matched ${found}/${requested} identifiers ${rng(r.range as any)}${trunc}\n (~${tok(num(r.estimatedTokens))} tokens)`; |
| 94 | +} |
| 95 | + |
| 96 | +function fmtCodeNeedWindow(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 97 | + const approved = r.approved; |
| 98 | + const status = approved ? "approved" : "denied"; |
| 99 | + const downgraded = r.downgradedFrom ? ` (downgraded from ${str(r.downgradedFrom)})` : ""; |
| 100 | + const est = num(r.estimatedTokens); |
| 101 | + if (!approved) { |
| 102 | + const next = str((r as any).nextBestAction); |
| 103 | + return `code.needWindow → [${status}]${next ? "\n Suggestion: " + next : ""}`; |
| 104 | + } |
| 105 | + return `code.needWindow → [${status}]${downgraded} ${rng(r.range as any)}\n (~${tok(est)} tokens)`; |
| 106 | +} |
| 107 | + |
| 108 | +function fmtSliceBuild(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 109 | + const cards = (r.cards as unknown[])?.length ?? (r.cardRefs as unknown[])?.length ?? 0; |
| 110 | + const handle = str(r.sliceHandle); |
| 111 | + const spillover = num(r.spilloverCount); |
| 112 | + const budget = r.budgetUsed as Record<string, unknown> | undefined; |
| 113 | + let line = `slice.build → ${cards} cards`; |
| 114 | + if (handle) line += ` (handle: ${handle.slice(0, 8)}…)`; |
| 115 | + if (spillover > 0) line += `\n ${spillover} in spillover`; |
| 116 | + if (budget) line += `\n Budget: ~${tok(num(budget.estimatedTokens))} tokens used`; |
| 117 | + return line; |
| 118 | +} |
| 119 | + |
| 120 | +function fmtSliceRefresh(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 121 | + const added = (r.addedCards as unknown[])?.length ?? 0; |
| 122 | + const removed = (r.removedSymbolIds as unknown[])?.length ?? 0; |
| 123 | + const updated = (r.updatedCards as unknown[])?.length ?? 0; |
| 124 | + return `slice.refresh → +${added} -${removed} ~${updated} cards`; |
| 125 | +} |
| 126 | + |
| 127 | +function fmtDeltaGet(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 128 | + const changes = (r.changes as unknown[])?.length ?? 0; |
| 129 | + const blast = (r.blastRadius as unknown[])?.length ?? 0; |
| 130 | + return `delta.get → ${changes} changed symbols${blast > 0 ? `, ${blast} in blast radius` : ""}`; |
| 131 | +} |
| 132 | + |
| 133 | +function fmtRepoStatus(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 134 | + const files = num(r.filesIndexed); |
| 135 | + const syms = num(r.symbolsIndexed); |
| 136 | + const health = num(r.healthScore); |
| 137 | + return `repo.status → ${files} files, ${syms} symbols, health ${health}/100`; |
| 138 | +} |
| 139 | + |
| 140 | +function fmtRepoOverview(_a: Record<string, unknown>, _r: Record<string, unknown>): string | null { |
| 141 | + const level = str(_a.level) || "stats"; |
| 142 | + return `repo.overview (${level})`; |
| 143 | +} |
| 144 | + |
| 145 | +function fmtIndexRefresh(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 146 | + const mode = str(_a.mode) || "incremental"; |
| 147 | + const files = num(r.filesProcessed ?? r.filesScanned); |
| 148 | + return `index.refresh (${mode}) → ${files} files processed`; |
| 149 | +} |
| 150 | + |
| 151 | +function fmtChain(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 152 | + const results = r.results as Array<Record<string, unknown>> | undefined; |
| 153 | + if (!results) return null; |
| 154 | + const ok = results.filter(s => s.status === "ok").length; |
| 155 | + const err = results.filter(s => s.status === "error").length; |
| 156 | + const total = num(r.totalTokens); |
| 157 | + let line = `chain → ${results.length} steps (${ok} ok`; |
| 158 | + if (err > 0) line += `, ${err} errors`; |
| 159 | + line += `)`; |
| 160 | + if (total > 0) line += ` ~${tok(total)} tokens`; |
| 161 | + return line; |
| 162 | +} |
| 163 | + |
| 164 | +function fmtAgentOrchestrate(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 165 | + const plan = r.plan as Record<string, unknown> | undefined; |
| 166 | + const rungs = (plan?.rungs as unknown[])?.length ?? 0; |
| 167 | + const status = str(r.status) || "complete"; |
| 168 | + return `agent.orchestrate [${status}] → ${rungs} rungs`; |
| 169 | +} |
| 170 | + |
| 171 | +function fmtMemoryStore(_a: Record<string, unknown>, _r: Record<string, unknown>): string | null { |
| 172 | + const title = str(_a.title); |
| 173 | + return `memory.store → "${truncName(title)}"`; |
| 174 | +} |
| 175 | + |
| 176 | +function fmtMemoryQuery(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 177 | + const memories = (r.memories as unknown[])?.length ?? 0; |
| 178 | + return `memory.query → ${memories} result${memories !== 1 ? "s" : ""}`; |
| 179 | +} |
| 180 | + |
| 181 | +function fmtPrRisk(_a: Record<string, unknown>, r: Record<string, unknown>): string | null { |
| 182 | + const score = num(r.overallRisk ?? r.riskScore); |
| 183 | + const items = (r.riskItems as unknown[])?.length ?? 0; |
| 184 | + return `pr.risk.analyze → risk ${score}/100, ${items} items`; |
| 185 | +} |
| 186 | + |
| 187 | +// --------------------------------------------------------------------------- |
| 188 | +// Registry |
| 189 | +// --------------------------------------------------------------------------- |
| 190 | + |
| 191 | +const formatters: Record<string, Formatter> = { |
| 192 | + "sdl.symbol.search": fmtSymbolSearch, |
| 193 | + "sdl.symbol.getCard": fmtSymbolGetCard, |
| 194 | + "sdl.symbol.getCards": fmtSymbolGetCards, |
| 195 | + "sdl.code.getSkeleton": fmtCodeSkeleton, |
| 196 | + "sdl.code.getHotPath": fmtCodeHotPath, |
| 197 | + "sdl.code.needWindow": fmtCodeNeedWindow, |
| 198 | + "sdl.slice.build": fmtSliceBuild, |
| 199 | + "sdl.slice.refresh": fmtSliceRefresh, |
| 200 | + "sdl.delta.get": fmtDeltaGet, |
| 201 | + "sdl.repo.status": fmtRepoStatus, |
| 202 | + "sdl.repo.overview": fmtRepoOverview, |
| 203 | + "sdl.index.refresh": fmtIndexRefresh, |
| 204 | + "sdl.chain": fmtChain, |
| 205 | + "sdl.agent.orchestrate": fmtAgentOrchestrate, |
| 206 | + "sdl.memory.store": fmtMemoryStore, |
| 207 | + "sdl.memory.query": fmtMemoryQuery, |
| 208 | + "sdl.pr.risk.analyze": fmtPrRisk, |
| 209 | +}; |
| 210 | + |
| 211 | +// --------------------------------------------------------------------------- |
| 212 | +// Public API |
| 213 | +// --------------------------------------------------------------------------- |
| 214 | + |
| 215 | +/** |
| 216 | + * Format a tool call + result as human-readable text for user display. |
| 217 | + * Returns null if no formatter is registered for the tool. |
| 218 | + */ |
| 219 | +export function formatToolCallForUser( |
| 220 | + toolName: string, |
| 221 | + args: Record<string, unknown>, |
| 222 | + result: unknown, |
| 223 | +): string | null { |
| 224 | + const fmt = formatters[toolName]; |
| 225 | + if (!fmt) return null; |
| 226 | + try { |
| 227 | + return fmt(args, (result ?? {}) as Record<string, unknown>); |
| 228 | + } catch { |
| 229 | + return null; |
| 230 | + } |
| 231 | +} |
0 commit comments