refactor(core): extract shared usage, auth, and display helpers

src/agents/tool-display-common.ts

@@ -51,6 +51,18 @@ export function normalizeVerb(value?: string): string | undefined {
   return trimmed.replace(/_/g, " ");
 }
 
+export function resolveActionArg(args: unknown): string | undefined {
+  if (!args || typeof args !== "object") {
+    return undefined;
+  }
+  const actionRaw = (args as Record<string, unknown>).action;
+  if (typeof actionRaw !== "string") {
+    return undefined;
+  }
+  const action = actionRaw.trim();
+  return action || undefined;
+}
+
 export function coerceDisplayValue(
   value: unknown,
   opts: CoerceDisplayValueOptions = {},
@@ -1118,3 +1130,80 @@ export function resolveDetailFromKeys(
     .map((entry) => `${entry.label} ${entry.value}`)
     .join(" · ");
 }
+
+export function resolveToolVerbAndDetail(params: {
+  toolKey: string;
+  args?: unknown;
+  meta?: string;
+  action?: string;
+  spec?: ToolDisplaySpec;
+  fallbackDetailKeys?: string[];
+  detailMode: "first" | "summary";
+  detailCoerce?: CoerceDisplayValueOptions;
+  detailMaxEntries?: number;
+  detailFormatKey?: (raw: string) => string;
+}): { verb?: string; detail?: string } {
+  const actionSpec = resolveActionSpec(params.spec, params.action);
+  const fallbackVerb =
+    params.toolKey === "web_search"
+      ? "search"
+      : params.toolKey === "web_fetch"
+        ? "fetch"
+        : params.toolKey.replace(/_/g, " ").replace(/\./g, " ");
+  const verb = normalizeVerb(actionSpec?.label ?? params.action ?? fallbackVerb);
+
+  let detail: string | undefined;
+  if (params.toolKey === "exec") {
+    detail = resolveExecDetail(params.args);
+  }
+  if (!detail && params.toolKey === "read") {
+    detail = resolveReadDetail(params.args);
+  }
+  if (
+    !detail &&
+    (params.toolKey === "write" || params.toolKey === "edit" || params.toolKey === "attach")
+  ) {
+    detail = resolveWriteDetail(params.toolKey, params.args);
+  }
+  if (!detail && params.toolKey === "web_search") {
+    detail = resolveWebSearchDetail(params.args);
+  }
+  if (!detail && params.toolKey === "web_fetch") {
+    detail = resolveWebFetchDetail(params.args);
+  }
+
+  const detailKeys =
+    actionSpec?.detailKeys ?? params.spec?.detailKeys ?? params.fallbackDetailKeys ?? [];
+  if (!detail && detailKeys.length > 0) {
+    detail = resolveDetailFromKeys(params.args, detailKeys, {
+      mode: params.detailMode,
+      coerce: params.detailCoerce,
+      maxEntries: params.detailMaxEntries,
+      formatKey: params.detailFormatKey,
+    });
+  }
+  if (!detail && params.meta) {
+    detail = params.meta;
+  }
+  return { verb, detail };
+}
+
+export function formatToolDetailText(
+  detail: string | undefined,
+  opts: { prefixWithWith?: boolean } = {},
+): string | undefined {
+  if (!detail) {
+    return undefined;
+  }
+  const normalized = detail.includes(" · ")
+    ? detail
+        .split(" · ")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .join(", ")
+    : detail;
+  if (!normalized) {
+    return undefined;
+  }
+  return opts.prefixWithWith ? `with ${normalized}` : normalized;
+}

src/agents/tool-display.ts

@@ -2,16 +2,11 @@ import { redactToolDetail } from "../logging/redact.js";
 import { shortenHomeInString } from "../utils.js";
 import {
   defaultTitle,
+  formatToolDetailText,
   formatDetailKey,
   normalizeToolName,
-  normalizeVerb,
-  resolveActionSpec,
-  resolveDetailFromKeys,
-  resolveExecDetail,
-  resolveReadDetail,
-  resolveWebFetchDetail,
-  resolveWebSearchDetail,
-  resolveWriteDetail,
+  resolveActionArg,
+  resolveToolVerbAndDetail,
   type ToolDisplaySpec as ToolDisplaySpecBase,
 } from "./tool-display-common.js";
 import TOOL_DISPLAY_JSON from "./tool-display.json" with { type: "json" };
@@ -69,51 +64,18 @@ export function resolveToolDisplay(params: {
   const emoji = spec?.emoji ?? FALLBACK.emoji ?? "🧩";
   const title = spec?.title ?? defaultTitle(name);
   const label = spec?.label ?? title;
-  const actionRaw =
-    params.args && typeof params.args === "object"
-      ? ((params.args as Record<string, unknown>).action as string | undefined)
-      : undefined;
-  const action = typeof actionRaw === "string" ? actionRaw.trim() : undefined;
-  const actionSpec = resolveActionSpec(spec, action);
-  const fallbackVerb =
-    key === "web_search"
-      ? "search"
-      : key === "web_fetch"
-        ? "fetch"
-        : key.replace(/_/g, " ").replace(/\./g, " ");
-  const verb = normalizeVerb(actionSpec?.label ?? action ?? fallbackVerb);
-
-  let detail: string | undefined;
-  if (key === "exec") {
-    detail = resolveExecDetail(params.args);
-  }
-  if (!detail && key === "read") {
-    detail = resolveReadDetail(params.args);
-  }
-  if (!detail && (key === "write" || key === "edit" || key === "attach")) {
-    detail = resolveWriteDetail(key, params.args);
-  }
-
-  if (!detail && key === "web_search") {
-    detail = resolveWebSearchDetail(params.args);
-  }
-
-  if (!detail && key === "web_fetch") {
-    detail = resolveWebFetchDetail(params.args);
-  }
-
-  const detailKeys = actionSpec?.detailKeys ?? spec?.detailKeys ?? FALLBACK.detailKeys ?? [];
-  if (!detail && detailKeys.length > 0) {
-    detail = resolveDetailFromKeys(params.args, detailKeys, {
-      mode: "summary",
-      maxEntries: MAX_DETAIL_ENTRIES,
-      formatKey: (raw) => formatDetailKey(raw, DETAIL_LABEL_OVERRIDES),
-    });
-  }
-
-  if (!detail && params.meta) {
-    detail = params.meta;
-  }
+  const action = resolveActionArg(params.args);
+  let { verb, detail } = resolveToolVerbAndDetail({
+    toolKey: key,
+    args: params.args,
+    meta: params.meta,
+    action,
+    spec,
+    fallbackDetailKeys: FALLBACK.detailKeys,
+    detailMode: "summary",
+    detailMaxEntries: MAX_DETAIL_ENTRIES,
+    detailFormatKey: (raw) => formatDetailKey(raw, DETAIL_LABEL_OVERRIDES),
+  });
 
   if (detail) {
     detail = shortenHomeInString(detail);
@@ -131,18 +93,7 @@ export function resolveToolDisplay(params: {
 
 export function formatToolDetail(display: ToolDisplay): string | undefined {
   const detailRaw = display.detail ? redactToolDetail(display.detail) : undefined;
-  if (!detailRaw) {
-    return undefined;
-  }
-  if (detailRaw.includes(" · ")) {
-    const compact = detailRaw
-      .split(" · ")
-      .map((part) => part.trim())
-      .filter((part) => part.length > 0)
-      .join(", ");
-    return compact ? `with ${compact}` : undefined;
-  }
-  return detailRaw;
+  return formatToolDetailText(detailRaw, { prefixWithWith: true });
 }
 
 export function formatToolSummary(display: ToolDisplay): string {