@dahrk/linear 0.1.0 → 0.2.0

package/src/format-action.ts

@@ -0,0 +1,279 @@
+/**
+ * Format a tool call into Linear's action-activity vocabulary (DHK-382): a human verb in
+ * `action` and a clean, humanised input in `parameter`. Linear renders these as
+ * "<action> · <parameter>" (e.g. "Ran · grep -rn ..."), so the agent session reads as a
+ * sequence of verbs instead of a wall of `ToolName {raw JSON args}`.
+ *
+ * `inputText` is the edge's bounded preview of the tool input: normally a JSON object string
+ * (`clip(JSON.stringify(input))`), but it may be TRUNCATED (over the edge's ~500-char cap) or
+ * otherwise malformed. Parsing is defensive: a preview that will not parse never throws and
+ * never falls through to raw JSON. Known single-field tools still salvage their primary field
+ * from a truncated preview; anything unrecoverable degrades to the bare verb.
+ */
+
+/** A tool call rendered as Linear's `{ action, parameter }` pair. */
+export interface ToolAction {
+  action: string;
+  parameter: string;
+}
+
+/** Keep a parameter readable on one line; the edge already caps the input at ~500 chars. */
+const MAX_PARAM = 400;
+
+/** Collapse whitespace to a single line and clip with an ellipsis so the parameter never wraps. */
+function clip(s: string, max = MAX_PARAM): string {
+  const t = s.replace(/\s+/g, " ").trim();
+  return t.length <= max ? t : `${t.slice(0, max - 1).trimEnd()}…`;
+}
+
+/** The final path segment (e.g. "packages/hub/src/config-server.ts" -> "config-server.ts"). */
+function basename(p: string): string {
+  const trimmed = p.replace(/\/+$/, "");
+  const i = trimmed.lastIndexOf("/");
+  return i >= 0 ? trimmed.slice(i + 1) : trimmed;
+}
+
+/** Humanise a tool name for display: split separators and camelCase, then Title Case
+ *  (e.g. "WebFetch" -> "Web Fetch", "create_issue" -> "Create Issue"). */
+function humaniseToolName(name: string): string {
+  return (
+    name
+      .replace(/[_-]+/g, " ")
+      .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+      .trim()
+      .replace(/\b\w/g, (c) => c.toUpperCase()) || "Tool"
+  );
+}
+
+/** A parsed tool-input object, or undefined when the preview is missing/truncated/not an object. */
+function parseInput(text: string | undefined): Record<string, unknown> | undefined {
+  const t = text?.trim();
+  if (!t || !t.startsWith("{")) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(t);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** A scalar field as a trimmed string, or undefined when absent/empty/non-scalar. */
+function scalarField(input: Record<string, unknown> | undefined, key: string): string | undefined {
+  const v = input?.[key];
+  const s = typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : undefined;
+  return s && s.trim() !== "" ? s : undefined;
+}
+
+/** Best-effort extraction of a string field straight from the raw preview, so a TRUNCATED JSON
+ *  (a long command clipped mid-value) still yields its primary field rather than an empty verb. */
+function looseField(text: string | undefined, key: string): string | undefined {
+  if (!text) return undefined;
+  const m = new RegExp(`"${key}"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)`).exec(text);
+  if (!m?.[1]) return undefined;
+  const decoded = m[1]
+    .replace(/\\"/g, '"')
+    .replace(/\\[nt]/g, " ")
+    .replace(/\\\\/g, "\\")
+    .replace(/\\$/, "");
+  return decoded.trim() !== "" ? decoded : undefined;
+}
+
+/** A known string field, preferring the parsed value and salvaging a truncated one from the raw text. */
+function stringField(
+  input: Record<string, unknown> | undefined,
+  text: string | undefined,
+  key: string,
+): string | undefined {
+  return scalarField(input, key) ?? looseField(text, key);
+}
+
+/** The first scalar argument of an unknown tool's input, for a best-guess parameter. */
+function firstScalar(input: Record<string, unknown> | undefined): string {
+  for (const key of Object.keys(input ?? {})) {
+    const s = scalarField(input, key);
+    if (s !== undefined) return s;
+  }
+  return "";
+}
+
+/** A `Read`/inspection line-range suffix (":440-520" or ":440") from numeric offset/limit. */
+function lineRange(input: Record<string, unknown> | undefined): string {
+  const offset = input?.offset;
+  const limit = input?.limit;
+  if (typeof offset !== "number") return "";
+  return typeof limit === "number" ? `:${offset}-${offset + limit}` : `:${offset}`;
+}
+
+/**
+ * Map a `(toolName, inputPreview)` pair to a verb plus a clean parameter. Total and defensive:
+ * every branch returns a `{ action, parameter }`, and the parameter is only ever a humanised
+ * field value (never the raw JSON), so a malformed or oversized preview degrades to the bare verb.
+ */
+export function formatToolAction(tool: string | undefined, inputText: string | undefined): ToolAction {
+  const name = (tool ?? "").trim();
+  const input = parseInput(inputText);
+  const field = (key: string): string | undefined => stringField(input, inputText, key);
+
+  switch (name) {
+    case "Bash":
+      return { action: "Ran", parameter: clip(field("command") ?? "") };
+    case "Read": {
+      const path = field("file_path");
+      return { action: "Read", parameter: path ? clip(basename(path) + lineRange(input)) : "" };
+    }
+    case "Grep": {
+      const pattern = field("pattern");
+      const path = field("path");
+      const where = pattern ? `"${pattern}"${path ? ` in ${path}` : ""}` : "";
+      return { action: "Searched", parameter: clip(where) };
+    }
+    case "Glob": {
+      const pattern = field("pattern");
+      const path = field("path");
+      const where = pattern ? `${pattern}${path ? ` in ${path}` : ""}` : "";
+      return { action: "Searched", parameter: clip(where) };
+    }
+    case "Edit":
+    case "MultiEdit": {
+      const path = field("file_path");
+      return { action: "Edited", parameter: path ? clip(basename(path)) : "" };
+    }
+    case "Write": {
+      const path = field("file_path");
+      return { action: "Wrote", parameter: path ? clip(basename(path)) : "" };
+    }
+    case "ToolSearch":
+      return { action: "Loaded tools", parameter: clip(field("query") ?? "") };
+    default:
+      break;
+  }
+
+  // MCP tools arrive as `mcp__<server>__<tool>`; show the humanised tool segment.
+  if (name.startsWith("mcp__")) {
+    const segments = name.split("__").filter(Boolean);
+    const toolSegment = segments[segments.length - 1] ?? name;
+    return { action: humaniseToolName(toolSegment), parameter: clip(firstScalar(input)) };
+  }
+
+  // Unknown tool: a title-cased name plus its first scalar argument.
+  return { action: humaniseToolName(name), parameter: clip(firstScalar(input)) };
+}
+
+/**
+ * Render a completed tool's output as the markdown `result` of its action activity (DHK-386). This
+ * is the companion to formatToolAction: the verb + parameter describe the call, this shapes the
+ * outcome per tool - `Bash` as a fenced block, `Grep` as a match-count summary, `Edit`/`Write` as a
+ * diff stat, `Read` as how much was read - so the session reads richly instead of dumping raw text.
+ *
+ * `output` is the tool's full (untruncated) observation output. Total and defensive like its
+ * companion: it never throws, bounds every long output with a clear elision so a noisy tool can
+ * never flood the session, and degrades any unrecognised tool or shape to a bounded first line. An
+ * empty output yields an empty string, so no `result` is folded onto the action.
+ */
+
+/** Caps for a rendered result: keep the outcome glanceable. Long output shows a head and tail with
+ *  a "… (N more lines)" marker between, never the whole wall. */
+const RESULT_MAX_LINES = 12;
+const RESULT_HEAD_LINES = 8;
+const RESULT_TAIL_LINES = 3;
+const RESULT_MAX_CHARS = 1800;
+const RESULT_TOP_HITS = 5;
+
+/** Clip a multi-line block to a character budget, marking the cut with an ellipsis line. */
+function clipBlock(s: string, max = RESULT_MAX_CHARS): string {
+  return s.length <= max ? s : `${s.slice(0, max).trimEnd()}\n…`;
+}
+
+/** Bound a block of lines: keep it whole when short, else show the head and tail with a
+ *  "… (N more lines)" elision marker between them so long output never becomes a wall of text. */
+function elideLines(lines: string[]): string {
+  if (lines.length <= RESULT_MAX_LINES) return lines.join("\n");
+  const head = lines.slice(0, RESULT_HEAD_LINES);
+  const tail = lines.slice(-RESULT_TAIL_LINES);
+  const omitted = lines.length - head.length - tail.length;
+  return [...head, `… (${omitted} more lines)`, ...tail].join("\n");
+}
+
+/** A fenced code block, the standard rendering for verbatim command/file output. */
+function codeFence(body: string): string {
+  return "```\n" + body + "\n```";
+}
+
+/** The first non-empty line, collapsed and clipped - the safe fallback for MCP and unknown tools. */
+function firstLine(output: string): string {
+  return clip(output.split("\n").find((l) => l.trim() !== "") ?? "");
+}
+
+/** English pluralisation for a count, e.g. `plural(2, "match", "matches")`. */
+function plural(n: number, one: string, many: string): string {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+/** `Bash`: the stdout/stderr in a fenced code block, bounded head + tail. */
+function renderBashResult(output: string): string {
+  return codeFence(clipBlock(elideLines(output.split("\n"))));
+}
+
+/** A `path:line` grep hit parsed from a `path:line:content` or `path:line` output row. */
+function grepHit(row: string): { path: string; line: string } | undefined {
+  const m = /^(.+?):(\d+)(?::|$)/.exec(row);
+  return m ? { path: m[1]!, line: m[2]! } : undefined;
+}
+
+/** `Grep`: an "N matches in M files" summary plus the first few ``path:line`` hits. Falls back to a
+ *  plain match count and the first rows when the output is not the `path:line` shape (e.g. a
+ *  files-with-matches listing of bare paths). */
+function renderGrepResult(output: string): string {
+  const rows = output.split("\n").map((r) => r.trim()).filter(Boolean);
+  const hits = rows.map(grepHit).filter((h): h is { path: string; line: string } => h !== undefined);
+  if (hits.length === 0) {
+    const listed = rows.slice(0, RESULT_TOP_HITS).map((r) => `- ${r}`);
+    const more = rows.length > RESULT_TOP_HITS ? [`… (${rows.length - RESULT_TOP_HITS} more)`] : [];
+    return [plural(rows.length, "match", "matches"), ...listed, ...more].join("\n");
+  }
+  const files = new Set(hits.map((h) => h.path)).size;
+  const summary = `${plural(hits.length, "match", "matches")} in ${plural(files, "file", "files")}`;
+  const top = hits.slice(0, RESULT_TOP_HITS).map((h) => `- \`${h.path}:${h.line}\``);
+  const more = hits.length > RESULT_TOP_HITS ? [`… (${hits.length - RESULT_TOP_HITS} more)`] : [];
+  return [summary, ...top, ...more].join("\n");
+}
+
+/** `Read`: how much was read; the file content itself is not worth echoing into the session. */
+function renderReadResult(output: string): string {
+  return `Read ${plural(output.split("\n").length, "line", "lines")}.`;
+}
+
+/** `Edit`/`Write`: a `+added / −removed` diff stat when the output is a unified diff, else the tool's
+ *  one-line confirmation. Ignores the `+++`/`---` file headers so they are not counted as changes. */
+function renderEditResult(output: string): string {
+  let added = 0;
+  let removed = 0;
+  for (const line of output.split("\n")) {
+    if (line.startsWith("+") && !line.startsWith("+++")) added += 1;
+    else if (line.startsWith("-") && !line.startsWith("---")) removed += 1;
+  }
+  return added > 0 || removed > 0 ? `\`+${added} / −${removed}\`` : firstLine(output);
+}
+
+export function formatToolResult(tool: string | undefined, output: string | undefined): string {
+  const text = (output ?? "").trimEnd();
+  if (text.trim() === "") return "";
+
+  switch ((tool ?? "").trim()) {
+    case "Bash":
+      return renderBashResult(text);
+    case "Grep":
+      return renderGrepResult(text);
+    case "Read":
+      return renderReadResult(text);
+    case "Edit":
+    case "MultiEdit":
+    case "Write":
+      return renderEditResult(text);
+    default:
+      // MCP and unknown tools: a short, safe summary rather than a raw dump.
+      return firstLine(text);
+  }
+}