@agent-native/core 0.164.4 → 0.164.12

package/corpus/templates/factory/app/routes/factory.tsx

@@ -1,5 +1,6 @@
 import {
   AgentToggleButton,
+  requestAgentChatThreadOpen,
   useChatModels,
 } from "@agent-native/core/client/agent-chat";
 import {
@@ -18,8 +19,9 @@ import {
   IconPlus,
   IconRefresh,
 } from "@tabler/icons-react";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { Link, useSearchParams } from "react-router";
+import { toast } from "sonner";
 
 import { FactoryAgentsView } from "@/components/factory/FactoryAgentsView";
 import { FactoryAuditView } from "@/components/factory/FactoryAuditView";
@@ -29,6 +31,7 @@ import {
   type FactoryCanvasGraph,
   type FactoryCanvasNode,
 } from "@/components/factory/FactoryCanvas";
+import { FactoryHistoryView } from "@/components/factory/FactoryHistoryView";
 import { FactoryInspector } from "@/components/factory/FactoryInspector";
 import { TriageStatusPill } from "@/components/triage/triage-status-pill";
 import { Button } from "@/components/ui/button";
@@ -78,6 +81,7 @@ type TriageDecision = {
 type TriageItem = {
   itemId?: string;
   id?: string;
+  title?: string | null;
   source?: string | null;
   sourceName?: string | null;
   sourceUrl?: string | null;
@@ -87,6 +91,8 @@ type TriageItem = {
   reason?: string | null;
   decisionSummary?: string | null;
   decisions?: TriageDecision[] | null;
+  createdAt?: string | null;
+  updatedAt?: string | null;
 };
 
 type TriageRule = {
@@ -126,6 +132,7 @@ type WorkspaceTab =
   | "automations"
   | "agents"
   | "audit"
+  | "history"
   | "settings";
 
 type FactoryAutomationRun = {
@@ -159,6 +166,7 @@ type FactoryAutomation = {
   timezone?: string | null;
   condition?: string | null;
   canUpdate?: boolean;
+  updatedAt?: string | number | null;
   runs?: FactoryAutomationRun[] | null;
   pastRuns?: FactoryAutomationRun[] | null;
 };
@@ -178,9 +186,14 @@ export default function FactoryRoute() {
   const [creating, setCreating] = useState(false);
   const [draftGraph, setDraftGraph] = useState<FactoryCanvasGraph | null>(null);
   const [dirty, setDirty] = useState(false);
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const [saveConflictRemoteGraph, setSaveConflictRemoteGraph] =
+    useState<FactoryCanvasGraph | null>(null);
+  const [refreshingFactory, setRefreshingFactory] = useState(false);
   const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
   const [selectedEdgeId, setSelectedEdgeId] = useState<string | null>(null);
   const [auditRefreshToken, setAuditRefreshToken] = useState(0);
+  const draftRevisionRef = useRef(0);
 
   function setActiveTab(tab: WorkspaceTab) {
     setSearchParams(
@@ -188,6 +201,10 @@ export default function FactoryRoute() {
         const next = new URLSearchParams(current);
         if (tab === "overview") next.delete("tab");
         else next.set("tab", tab);
+        if (tab === "history") {
+          next.delete("node");
+          next.delete("edge");
+        }
         return next;
       },
       { replace: true },
@@ -249,17 +266,17 @@ export default function FactoryRoute() {
   const graphData =
     rawGraphData?.factory.id === factoryId ? rawGraphData : undefined;
   const graph = draftGraph ?? graphData?.graph ?? null;
-  const graphVersion = graphData?.factory.graphVersion ?? graph?.version ?? 1;
+  const graphVersion = graph?.version ?? graphData?.factory.graphVersion ?? 1;
   const saveGraphMutation = useActionMutation("save-factory-graph");
   const factoryList = (factoryListQuery.data ?? []) as FactorySummary[];
 
   useEffect(() => {
-    if (!graphData || creating) return;
+    if (!graphData || creating || dirty) return;
     setDraftGraph(graphData.graph);
     setDirty(false);
     setSelectedNodeId(null);
     setSelectedEdgeId(null);
-  }, [creating, graphData]);
+  }, [creating, dirty, graphData]);
 
   useEffect(() => {
     setSelectedNodeId(searchParams.get("node"));
@@ -307,6 +324,9 @@ export default function FactoryRoute() {
   }
 
   function updateGraph(next: FactoryCanvasGraph) {
+    draftRevisionRef.current += 1;
+    setSaveError(null);
+    setSaveConflictRemoteGraph(null);
     setDraftGraph(next);
     setDirty(
       !graphData?.graph ||
@@ -390,20 +410,87 @@ export default function FactoryRoute() {
 
   async function saveGraph() {
     if (!graph || !selectedFactoryId) return;
-    await saveGraphMutation.mutateAsync({
-      factoryId: selectedFactoryId,
-      name: graph.name,
-      description: graph.description,
-      prompt: creating ? "" : (graphData?.factory.prompt ?? ""),
-      source: "manual",
-      changeSummary: creating
-        ? "Created from the Factory visual editor."
-        : "Updated in the Factory visual editor.",
-      graph,
-    });
+    const submittedDraftRevision = draftRevisionRef.current;
+    setSaveError(null);
+    try {
+      await saveGraphMutation.mutateAsync({
+        factoryId: selectedFactoryId,
+        name: graph.name,
+        description: graph.description,
+        prompt: creating ? "" : (graphData?.factory.prompt ?? ""),
+        source: "manual",
+        changeSummary: creating
+          ? "Created from the Factory visual editor."
+          : "Updated in the Factory visual editor.",
+        expectedGraphVersion: creating ? 0 : graph.version,
+        graph,
+      });
+      setCreating(false);
+      setDirty(draftRevisionRef.current !== submittedDraftRevision);
+      setSaveConflictRemoteGraph(null);
+      await Promise.all([graphQuery.refetch(), factoryListQuery.refetch()]);
+    } catch (error) {
+      setSaveError(
+        error instanceof Error
+          ? error.message
+          : t("factoryRoute.saveConflictFallback"),
+      );
+    }
+  }
+
+  async function refreshFactoryAfterSaveConflict() {
+    setRefreshingFactory(true);
+    try {
+      const results = await Promise.all([
+        graphQuery.refetch(),
+        factoryListQuery.refetch(),
+      ]);
+      if (results.some((result) => result.isError)) {
+        throw new Error("Factory refresh failed.");
+      }
+      const remoteGraph = (results[0].data as FactoryGraphResponse | undefined)
+        ?.graph;
+      if (dirty) {
+        if (!remoteGraph) throw new Error("Factory graph refresh failed.");
+        setSaveConflictRemoteGraph(remoteGraph);
+        setSaveError(t("factoryRoute.saveConflictFallback"));
+        return;
+      }
+      setSaveError(null);
+    } catch {
+      setSaveError(t("factoryRoute.saveConflictFallback"));
+    } finally {
+      setRefreshingFactory(false);
+    }
+  }
+
+  function discardLocalFactoryChanges() {
+    if (!saveConflictRemoteGraph) return;
+    setDraftGraph(saveConflictRemoteGraph);
+    setSaveConflictRemoteGraph(null);
+    setSaveError(null);
+    setDirty(false);
     setCreating(false);
+    setSelectedNodeId(null);
+    setSelectedEdgeId(null);
+  }
+
+  async function handleFactoryRestored(result?: { graph: FactoryCanvasGraph }) {
+    setCreating(false);
+    if (result?.graph) setDraftGraph(result.graph);
+    else setDraftGraph(null);
     setDirty(false);
-    await Promise.all([graphQuery.refetch(), factoryListQuery.refetch()]);
+    setSaveError(null);
+    setSaveConflictRemoteGraph(null);
+    setSelectedNodeId(null);
+    setSelectedEdgeId(null);
+    const results = await Promise.all([
+      graphQuery.refetch(),
+      factoryListQuery.refetch(),
+    ]);
+    if (results.some((result) => result.isError)) {
+      throw new Error("Factory view refresh failed.");
+    }
   }
 
   if (!selectedFactoryId && activeTab === "agents") {
@@ -653,6 +740,12 @@ export default function FactoryRoute() {
             >
               Activity
             </TabButton>
+            <TabButton
+              active={activeTab === "history"}
+              onClick={() => setActiveTab("history")}
+            >
+              {t("factoryRoute.historyTab")}
+            </TabButton>
             <TabButton
               active={activeTab === "settings"}
               onClick={() => setActiveTab("settings")}
@@ -721,8 +814,13 @@ export default function FactoryRoute() {
               factoryId={factoryId}
               dirty={dirty}
               saving={saveGraphMutation.isPending}
+              saveError={saveError}
+              saveConflictNeedsResolution={Boolean(saveConflictRemoteGraph)}
+              refreshing={refreshingFactory}
               onGraphChange={updateGraph}
               onSave={() => void saveGraph()}
+              onRefresh={refreshFactoryAfterSaveConflict}
+              onDiscardLocalChanges={discardLocalFactoryChanges}
               onAddNode={addNode}
               onDeleteNode={deleteNode}
               onConnect={connectNodes}
@@ -741,6 +839,13 @@ export default function FactoryRoute() {
             factoryId={factoryId}
             refreshToken={auditRefreshToken}
           />
+        ) : activeTab === "history" ? (
+          <FactoryHistoryView
+            key={factoryId}
+            factoryId={factoryId}
+            hasUnsavedChanges={dirty}
+            onRestored={handleFactoryRestored}
+          />
         ) : (
           <SettingsView t={t} />
         )}
@@ -777,6 +882,7 @@ function parseWorkspaceTab(value: string | null): WorkspaceTab {
     value === "automations" ||
     value === "agents" ||
     value === "audit" ||
+    value === "history" ||
     value === "settings"
     ? value
     : "overview";
@@ -976,7 +1082,8 @@ function AutomationsView({
         current.body === nextDraft.body &&
         current.model === nextDraft.model &&
         current.schedule === nextDraft.schedule &&
-        current.enabled === nextDraft.enabled
+        current.enabled === nextDraft.enabled &&
+        current.updatedAt === nextDraft.updatedAt
       ) {
         return current;
       }
@@ -986,16 +1093,25 @@ function AutomationsView({
 
   async function saveAutomation() {
     if (!draft) return;
-    await saveMutation.mutateAsync({
-      factoryId,
-      automationId: draft.id,
-      name: draft.name,
-      prompt: draft.prompt ?? draft.body ?? "",
-      model: draft.model ?? "",
-      schedule: draft.schedule ?? "",
-      enabled: draft.enabled,
-    });
-    await automationsQuery.refetch();
+    try {
+      await saveMutation.mutateAsync({
+        factoryId,
+        automationId: draft.id,
+        name: draft.name,
+        prompt: draft.prompt ?? draft.body ?? "",
+        model: draft.model ?? "",
+        schedule: draft.schedule ?? "",
+        enabled: draft.enabled,
+      });
+      await automationsQuery.refetch();
+      toast.success(t("factoryRoute.automationSaved"));
+    } catch (error) {
+      toast.error(
+        error instanceof Error
+          ? error.message
+          : t("factoryRoute.automationSaveFailed"),
+      );
+    }
   }
 
   async function runAutomation() {
@@ -1031,27 +1147,34 @@ function AutomationsView({
                 role="tablist"
                 aria-label={t("factoryRoute.automationsTitle")}
               >
-                {automations.map((automation) => (
-                  <button
-                    key={automation.id}
-                    type="button"
-                    id={`factory-automation-tab-${automation.id}`}
-                    role="tab"
-                    aria-selected={activeAutomationId === automation.id}
-                    aria-controls="factory-automation-panel"
-                    className={`w-full cursor-pointer rounded-lg bg-muted/20 p-4 text-left transition-colors hover:bg-muted/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring ${activeAutomationId === automation.id ? "bg-muted/60" : ""}`}
-                    onClick={() => selectAutomation(automation.id)}
-                  >
-                    <span className="block truncate text-sm font-medium">
-                      {automation.name}
-                    </span>
-                    <span className="mt-1 block truncate text-xs text-muted-foreground">
-                      {automation.enabled
-                        ? t("factoryRoute.automationEnabled")
-                        : t("factoryRoute.automationDisabled")}
-                    </span>
-                  </button>
-                ))}
+                {automations.map((automation) => {
+                  const selected = activeAutomationId === automation.id;
+                  return (
+                    <button
+                      key={automation.id}
+                      type="button"
+                      id={`factory-automation-tab-${automation.id}`}
+                      role="tab"
+                      aria-selected={selected}
+                      aria-controls="factory-automation-panel"
+                      className={`w-full cursor-pointer rounded-lg p-4 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring ${
+                        selected
+                          ? "bg-primary/10 ring-1 ring-inset ring-primary/40"
+                          : "bg-muted/20 hover:bg-muted/50"
+                      }`}
+                      onClick={() => selectAutomation(automation.id)}
+                    >
+                      <span className="block truncate text-sm font-medium">
+                        {automation.name}
+                      </span>
+                      <span className="mt-1 block truncate text-xs text-muted-foreground">
+                        {automation.enabled
+                          ? t("factoryRoute.automationEnabled")
+                          : t("factoryRoute.automationDisabled")}
+                      </span>
+                    </button>
+                  );
+                })}
               </div>
             )}
           </CardContent>
@@ -1189,8 +1312,24 @@ function AutomationsView({
                   </div>
                 </div>
                 <div className="grid gap-1.5">
-                  <Label>{t("factoryRoute.automationPrompt")}</Label>
+                  <div className="flex flex-wrap items-baseline gap-x-2 gap-y-0.5">
+                    <Label htmlFor="factory-automation-prompt">
+                      {t("factoryRoute.automationPrompt")}
+                    </Label>
+                    {draft.updatedAt ? (
+                      <span className="capitalize text-xs text-muted-foreground">
+                        {t("factoryRoute.automationLastUpdated")}{" "}
+                        <time
+                          dateTime={new Date(draft.updatedAt).toISOString()}
+                          title={formatAutomationDate(draft.updatedAt)}
+                        >
+                          {formatInboxDateTime(draft.updatedAt)}
+                        </time>
+                      </span>
+                    ) : null}
+                  </div>
                   <Textarea
+                    id="factory-automation-prompt"
                     value={draft.prompt ?? draft.body ?? ""}
                     onChange={(event) =>
                       setDraft({ ...draft, prompt: event.target.value })
@@ -1226,11 +1365,25 @@ function AutomationsView({
                             </span>
                             {run.threadId && (
                               <a
-                                className="inline-flex items-center gap-1 text-xs text-muted-foreground underline-offset-4 hover:underline"
+                                className="inline-flex items-center text-xs text-muted-foreground underline-offset-4 hover:underline"
                                 href={`/chat/${encodeURIComponent(run.threadId)}`}
+                                onClick={(event) => {
+                                  if (
+                                    event.metaKey ||
+                                    event.ctrlKey ||
+                                    event.shiftKey ||
+                                    event.altKey ||
+                                    event.button !== 0
+                                  ) {
+                                    return;
+                                  }
+                                  event.preventDefault();
+                                  requestAgentChatThreadOpen({
+                                    threadId: run.threadId!,
+                                  });
+                                }}
                               >
                                 {t("factoryRoute.automationOpenThread")}
-                                <IconExternalLink className="size-3" />
                               </a>
                             )}
                             {run.error && (
@@ -1259,6 +1412,52 @@ function formatAutomationDate(value: string | number | null | undefined) {
   return Number.isNaN(date.getTime()) ? String(value) : date.toLocaleString();
 }
 
+function formatInboxDateTime(value: string | number | null | undefined) {
+  if (!value) return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return String(value);
+  return date.toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+}
+
+function formatInboxAge(value: string | number | null | undefined) {
+  if (!value) return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return String(value);
+
+  const elapsedSeconds = Math.max(
+    0,
+    Math.floor((Date.now() - date.getTime()) / 1_000),
+  );
+  if (elapsedSeconds < 60) return "now";
+  const elapsedMinutes = Math.floor(elapsedSeconds / 60);
+  if (elapsedMinutes < 60) return `${elapsedMinutes}m`;
+  const elapsedHours = Math.floor(elapsedMinutes / 60);
+  if (elapsedHours < 24) return `${elapsedHours}h`;
+  const elapsedDays = Math.floor(elapsedHours / 24);
+  if (elapsedDays < 30) return `${elapsedDays}d`;
+  const elapsedMonths = Math.floor(elapsedDays / 30);
+  if (elapsedMonths < 12) return `${elapsedMonths}mo`;
+  return `${Math.floor(elapsedMonths / 12)}y`;
+}
+
+const reviewListColumns =
+  "w-full gap-3 sm:grid-cols-[minmax(0,1.3fr)_minmax(4.75rem,auto)_minmax(5.5rem,auto)_minmax(4.5rem,auto)_minmax(0,1.3fr)] sm:items-start";
+
+function formatInboxSource(source: string | null | undefined) {
+  const normalized = source?.toLowerCase() ?? "";
+  if (normalized.includes("slack")) return "Slack";
+  if (normalized.includes("github")) return "GitHub";
+  if (normalized.includes("sentry")) return "Sentry";
+  const trimmed = source?.trim();
+  return trimmed ? trimmed : "Source";
+}
+
 function formatModelName(model: string | null | undefined) {
   const value = model?.trim();
   if (!value) return "the app default";
@@ -1279,6 +1478,7 @@ function InboxView({ t }: { t: ReturnType<typeof useT> }) {
   );
   const [feedbackNote, setFeedbackNote] = useState("");
   const [verdict, setVerdict] = useState<Verdict | null>(null);
+  const selectedRowRef = useRef<HTMLButtonElement | null>(null);
   const listQuery = useActionQuery("list-triage-items", {
     limit: 50,
     ...(status.trim()
@@ -1312,6 +1512,14 @@ function InboxView({ t }: { t: ReturnType<typeof useT> }) {
     setSelectedId(searchParams.get("itemId"));
   }, [searchParams]);
 
+  useEffect(() => {
+    if (!selectedId) return;
+    selectedRowRef.current?.scrollIntoView({
+      block: "nearest",
+      inline: "nearest",
+    });
+  }, [selectedId, normalizedItems.length]);
+
   function selectItem(itemId: string) {
     setSelectedId(itemId);
     setVerdict(null);
@@ -1371,19 +1579,51 @@ function InboxView({ t }: { t: ReturnType<typeof useT> }) {
             </p>
           ) : (
             <div className="grid gap-1.5 p-2">
+              <div
+                className={`hidden px-4 py-2 text-[11px] uppercase tracking-wide text-muted-foreground sm:grid ${reviewListColumns}`}
+              >
+                <span />
+                <span>{t("triage.risk")}</span>
+                <span>{t("triage.status")}</span>
+                <span>{t("triage.updatedAt")}</span>
+                <span>{t("triage.reason")}</span>
+              </div>
               {normalizedItems.map((item) => {
                 const id = item.itemId ?? item.id ?? "";
+                const selected = selectedId === id;
+                const createdAtLabel = formatInboxDateTime(item.createdAt);
+                const updatedAge = formatInboxAge(item.updatedAt);
                 return (
                   <button
                     key={id}
+                    ref={selected ? selectedRowRef : undefined}
                     type="button"
-                    className={`grid w-full gap-3 rounded-lg bg-muted/20 p-4 text-left transition-colors hover:bg-muted/50 sm:grid-cols-[1.1fr_.7fr_.9fr_1.6fr] ${selectedId === id ? "bg-muted/60" : ""}`}
+                    aria-current={selected ? "true" : undefined}
+                    className={`grid rounded-lg px-4 py-3 text-left transition-colors ${reviewListColumns} ${
+                      selected
+                        ? "bg-primary/10 ring-1 ring-inset ring-primary/40"
+                        : "bg-muted/20 hover:bg-muted/50"
+                    }`}
                     onClick={() => selectItem(id)}
                   >
                     <span className="min-w-0">
+                      <span className="block text-[11px] uppercase tracking-wide text-muted-foreground">
+                        {formatInboxSource(item.source ?? item.sourceName)}
+                      </span>
                       <span className="block truncate text-sm font-medium">
-                        {item.sourceName ?? item.source ?? "Unknown source"}
+                        {item.title?.trim() ||
+                          item.sourceName ||
+                          item.source ||
+                          "Untitled"}
                       </span>
+                      {createdAtLabel && item.createdAt && (
+                        <time
+                          className="mt-0.5 block text-xs text-muted-foreground"
+                          dateTime={item.createdAt}
+                        >
+                          {createdAtLabel}
+                        </time>
+                      )}
                       {item.sourceUrl && (
                         <span className="mt-1 flex max-w-full items-center gap-1 truncate text-xs text-primary">
                           {item.sourceUrl}
@@ -1392,20 +1632,36 @@ function InboxView({ t }: { t: ReturnType<typeof useT> }) {
                       )}
                     </span>
                     <span>
-                      <span className="block text-[11px] uppercase tracking-wide text-muted-foreground">
-                        Risk
+                      <span className="mb-1 block text-[11px] uppercase tracking-wide text-muted-foreground sm:hidden">
+                        {t("triage.risk")}
                       </span>
                       <TriageStatusPill status={item.risk} />
                     </span>
                     <span>
-                      <span className="block text-[11px] uppercase tracking-wide text-muted-foreground">
-                        Status
+                      <span className="mb-1 block text-[11px] uppercase tracking-wide text-muted-foreground sm:hidden">
+                        {t("triage.status")}
                       </span>
                       <TriageStatusPill status={item.status} />
                     </span>
-                    <span className="truncate">
-                      <span className="block text-[11px] uppercase tracking-wide text-muted-foreground">
-                        Reason
+                    <span>
+                      <span className="mb-1 block text-[11px] uppercase tracking-wide text-muted-foreground sm:hidden">
+                        {t("triage.updatedAt")}
+                      </span>
+                      {updatedAge && item.updatedAt ? (
+                        <time
+                          className="text-sm tabular-nums text-muted-foreground"
+                          dateTime={item.updatedAt}
+                          title={formatAutomationDate(item.updatedAt)}
+                        >
+                          {updatedAge}
+                        </time>
+                      ) : (
+                        <span className="text-sm text-muted-foreground">-</span>
+                      )}
+                    </span>
+                    <span className="min-w-0 truncate">
+                      <span className="mb-1 block text-[11px] uppercase tracking-wide text-muted-foreground sm:hidden">
+                        {t("triage.reason")}
                       </span>
                       <span className="text-sm">
                         {item.reason ?? item.decisionSummary ?? "-"}
@@ -1431,8 +1687,15 @@ function InboxView({ t }: { t: ReturnType<typeof useT> }) {
             <>
               <div className="flex items-start justify-between gap-3">
                 <div>
+                  <p className="text-[11px] uppercase tracking-wide text-muted-foreground">
+                    {formatInboxSource(
+                      selectedItem.source ?? selectedItem.sourceName,
+                    )}
+                  </p>
                   <p className="text-sm font-medium">
-                    {selectedItem.sourceName ?? selectedItem.source}
+                    {selectedItem.title?.trim() ||
+                      selectedItem.sourceName ||
+                      selectedItem.source}
                   </p>
                   {selectedItem.sourceUrl && (
                     <a

package/corpus/templates/factory/server/connectors/slack.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 export type Workspace = "primary" | "secondary";
 
 export type SlackTokenResolver = (workspace: Workspace) => Promise<string>;
@@ -20,6 +22,12 @@ export interface SlackTeamInfo {
   domain: string;
 }
 
+export interface SlackUserInfo {
+  id: string;
+  name: string | null;
+  displayName: string | null;
+}
+
 export interface ChannelHistoryResult {
   messages: SlackMessage[];
   has_more: boolean;
@@ -65,16 +73,20 @@ async function getToken(
   );
 }
 
+function slackCacheScope(token: string): string {
+  return createHash("sha256").update(token).digest("hex").slice(0, 16);
+}
+
 async function slackApi<T>(
   workspace: Workspace,
   method: string,
   params: Record<string, string> | undefined,
   tokenResolver?: SlackTokenResolver,
 ): Promise<T> {
-  const cacheKey = `${workspace}:${method}:${JSON.stringify(params ?? {})}`;
+  const token = await getToken(workspace, tokenResolver);
+  const cacheKey = `${workspace}:${slackCacheScope(token)}:${method}:${JSON.stringify(params ?? {})}`;
   const cached = cache.get(cacheKey);
   if (cached && cached.expiresAt > Date.now()) return cached.value as T;
-  const token = await getToken(workspace, tokenResolver);
   const url = new URL(`https://slack.com/api/${method}`);
   for (const [key, value] of Object.entries(params ?? {}))
     url.searchParams.set(key, value);
@@ -255,3 +267,33 @@ export async function getTeamInfo(
   );
   return data.team ?? { id: data.team_id ?? "", name: workspace, domain: "" };
 }
+
+export async function getUserInfo(
+  workspace: Workspace,
+  userId: string,
+  tokenResolver?: SlackTokenResolver,
+): Promise<SlackUserInfo> {
+  const id = userId.trim();
+  if (!id) throw new Error("A Slack user id is required.");
+  const data = await slackApi<{
+    user?: {
+      id?: string;
+      name?: string;
+      profile?: { display_name?: string };
+    };
+  }>(workspace, "users.info", { user: id }, tokenResolver);
+  const user = data.user;
+  if (!user || typeof user.id !== "string" || !user.id.trim()) {
+    throw new Error("Slack user response is missing a user id.");
+  }
+  const displayName =
+    typeof user.profile?.display_name === "string"
+      ? user.profile.display_name.trim()
+      : "";
+  const name = typeof user.name === "string" ? user.name.trim() : "";
+  return {
+    id: user.id.trim(),
+    name: name || null,
+    displayName: displayName || null,
+  };
+}