Open-source SEO, GEO, and marketing skills for AI agents.
feat(chat): natural-language tool intents + capture MCP arguments as labels
Yuting Zhong0feb32e6b3d8
diff --git a/notfair/src/components/chat/tool-intent.ts b/notfair/src/components/chat/tool-intent.tsindex a2a29649..bf104110 100644--- a/notfair/src/components/chat/tool-intent.ts+++ b/notfair/src/components/chat/tool-intent.ts@@ -102,12 +102,80 @@ export function humanizeTool(name: string, label: string | null): ToolIntent {return { verb: "Fetched URL", target: label ?? undefined };if (n === "websearch" || n === "search" || n === "google")return { verb: "Searched the web", target: label ?? undefined };- // MCP / generic tool — strip namespace prefixes and pretty-print the action.- const action = formatToolName(name);- return {- verb: `Called ${prettifyToolAction(action)}`,- target: label ?? undefined,- };+ // MCP / generic tool — strip namespace prefixes and speak the action+ // in natural language ("Listed ad accounts", "Ran a query", …).+ return mcpActionIntent(formatToolName(name), label);+}++/**+ * Natural-language intent for an MCP/generic action name. The convention+ * across the catalog is verb-first camelCase (`listAdAccounts`,+ * `updateCampaignBudget`, `exec`), so the leading token picks the verb+ * phrase and the rest names the object. Unknown verbs fall back to+ * "Called <action>" — honest, never wrong.+ */+function mcpActionIntent(action: string, label: string | null): ToolIntent {+ const pretty = prettifyToolAction(action); // e.g. "list ad accounts"+ const [head = "", ...rest] = pretty.split(" ");+ const obj = rest.join(" ");+ const target = label ?? undefined;+ // SQL-looking labels beat name heuristics: whatever the tool is called,+ // the user is looking at a query.+ const sqlish =+ !!label && /^\s*(select|with|insert|delete\s+from|update\s+\w+\s+set)\b/i.test(label);+ switch (head.toLowerCase()) {+ case "exec":+ case "execute":+ case "query":+ case "hogql":+ return { verb: sqlish ? "Ran a query" : "Ran a command", target };+ case "run":+ return { verb: obj ? `Ran ${obj}` : sqlish ? "Ran a query" : "Ran a task", target };+ case "list":+ return { verb: obj ? `Listed ${obj}` : "Listed records", target };+ case "get":+ case "fetch":+ case "read":+ return { verb: obj ? `Fetched ${obj}` : "Fetched data", target };+ case "search":+ return { verb: obj ? `Searched ${obj}` : "Searched", target };+ case "create":+ case "add":+ return { verb: obj ? `Created ${obj}` : "Created a record", target };+ case "update":+ case "set":+ case "amend":+ return { verb: obj ? `Updated ${obj}` : "Updated a record", target };+ case "delete":+ case "remove":+ return { verb: obj ? `Removed ${obj}` : "Removed a record", target };+ case "enable":+ return { verb: `Enabled ${obj || "a resource"}`, target };+ case "pause":+ return { verb: `Paused ${obj || "a resource"}`, target };+ case "resume":+ return { verb: `Resumed ${obj || "a resource"}`, target };+ case "rename":+ return { verb: `Renamed ${obj || "a resource"}`, target };+ case "propose":+ return { verb: `Proposed ${obj || "a change"}`, target };+ case "log":+ return { verb: `Logged ${obj || "a record"}`, target };+ case "review":+ return { verb: `Reviewed ${obj || "a record"}`, target };+ case "register":+ return { verb: `Registered ${obj || "a record"}`, target };+ case "backfill":+ return { verb: `Backfilled ${obj || "history"}`, target };+ case "verify":+ return { verb: `Verified ${obj || "a definition"}`, target };+ case "upload":+ return { verb: `Uploaded ${obj || "data"}`, target };+ case "send":+ return { verb: `Sent ${obj || "a message"}`, target };+ default:+ return { verb: `Called ${pretty}`, target };+ }}const SHELL_WRAPPER_RE =diff --git a/notfair/src/components/chat/transcript-model.test.ts b/notfair/src/components/chat/transcript-model.test.tsindex a3070414..e61f2102 100644--- a/notfair/src/components/chat/transcript-model.test.ts+++ b/notfair/src/components/chat/transcript-model.test.ts@@ -122,11 +122,21 @@ describe("humanizeTool", () => {);});- it("prettifies namespaced MCP tool names", () => {+ it("speaks MCP actions in natural language", () => {expect(humanizeTool("notfair_growth__notfair_googleads__listAdAccounts", null).verb,- ).toBe("Called list ad accounts");+ ).toBe("Listed ad accounts");+ expect(humanizeTool("posthog.exec", "SELECT count() FROM events")).toEqual({+ verb: "Ran a query",+ target: "SELECT count() FROM events",+ });+ expect(humanizeTool("mcp__X__updateCampaignBudget", null).verb).toBe(+ "Updated campaign budget",+ );+ expect(humanizeTool("mcp__X__frobnicateWidget", null).verb).toBe(+ "Called frobnicate widget",+ );});});diff --git a/notfair/src/server/adapters/claude-code-local/parse.ts b/notfair/src/server/adapters/claude-code-local/parse.tsindex f3167ca3..e9224f53 100644--- a/notfair/src/server/adapters/claude-code-local/parse.ts+++ b/notfair/src/server/adapters/claude-code-local/parse.ts@@ -1,4 +1,5 @@import type { HarnessEvent } from "../types";+import { labelFromArgs } from "../label-args";/*** Claude Code emits one JSON object per line on stdout when invoked with@@ -174,7 +175,10 @@ function labelForToolInput(name: string, input: unknown): string | undefined {// URLsconst url = tryKey("url") ?? tryKey("uri");if (url) return url;- return undefined;+ // Everything else (MCP calls especially): broad string-key extraction+ // plus a compact k=v digest, so no call lands label-less while its+ // arguments held something scannable.+ return labelFromArgs(obj);}function shortenPath(p: string): string {diff --git a/notfair/src/server/adapters/codex-local/parse.ts b/notfair/src/server/adapters/codex-local/parse.tsindex 96c1004e..d5e3cd1f 100644--- a/notfair/src/server/adapters/codex-local/parse.ts+++ b/notfair/src/server/adapters/codex-local/parse.ts@@ -1,4 +1,5 @@import type { HarnessEvent } from "../types";+import { labelFromArgs } from "../label-args";/*** Codex CLI emits one JSON event per line on stdout when invoked with@@ -253,16 +254,8 @@ function labelForCodexInput(const firstLine = item.command.split("\n")[0];return firstLine.length > 160 ? `${firstLine.slice(0, 159)}…` : firstLine;}- if (!item.arguments) return undefined;- const tryKey = (k: string): string | null => {- const v = item.arguments?.[k];- return typeof v === "string" && v.trim().length > 0 ? v.trim() : null;- };- return (- tryKey("file_path") ??- tryKey("path") ??- tryKey("url") ??- tryKey("query") ??- undefined- );+ // Broad extraction + compact k=v fallback — every MCP call should carry+ // a human-scannable label (the SQL text, the URL, the id being acted+ // on) into the transcript, not just the four keys we used to sample.+ return labelFromArgs(item.arguments);}diff --git a/notfair/src/server/adapters/label-args.ts b/notfair/src/server/adapters/label-args.tsnew file mode 100644index 00000000..2d671147--- /dev/null+++ b/notfair/src/server/adapters/label-args.ts@@ -0,0 +1,69 @@+/**+ * Shared tool-argument → transcript-label extraction for the harness+ * adapters. The harnesses expose every MCP call's full arguments; the+ * label is the one slot that survives into the transcript, so the goal+ * here is: no MCP call should land with an empty label while its+ * arguments held something a human could scan (the SQL text, the URL,+ * the campaign id…).+ */++/** Argument keys whose string value is the natural one-line label. */+const STRING_KEYS = [+ "file_path",+ "path",+ "filename",+ "url",+ "uri",+ "query",+ "sql",+ "hogql",+ "code",+ "script",+ "command",+ "cmd",+ "message",+ "text",+ "prompt",+ "statement",+ "name",+ "title",+ "description",+] as const;++function firstLine(s: string): string {+ const nl = s.indexOf("\n");+ return nl >= 0 ? s.slice(0, nl) : s;+}++function clip(s: string, max: number): string {+ return s.length > max ? `${s.slice(0, max - 1)}…` : s;+}++/**+ * Best human-scannable one-liner for a tool's arguments: a well-known+ * string field when present, otherwise a compact `key=value` digest of+ * the primitive arguments. Returns undefined only for empty/absent args.+ */+export function labelFromArgs(+ args: Record<string, unknown> | undefined | null,+): string | undefined {+ if (!args) return undefined;+ for (const k of STRING_KEYS) {+ const v = args[k];+ if (typeof v === "string" && v.trim().length > 0) {+ return clip(firstLine(v.trim()), 160);+ }+ }+ const parts: string[] = [];+ for (const [k, v] of Object.entries(args)) {+ if (v == null) continue;+ if (typeof v === "string") {+ if (v.trim().length > 0) parts.push(`${k}=${clip(firstLine(v.trim()), 40)}`);+ } else if (typeof v === "number" || typeof v === "boolean") {+ parts.push(`${k}=${v}`);+ }+ if (parts.length >= 4) break;+ }+ if (parts.length === 0) return undefined;+ return clip(parts.join(" "), 160);+}