Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(goals): metric provenance dialog + real next-check time on the goal rail

Yuting Zhonga3fd84517d20
diff --git a/notfair/src/app/(app)/[project]/goals/[agent]/page.tsx b/notfair/src/app/(app)/[project]/goals/[agent]/page.tsx
index 3f158ef2..6ddf2c49 100644
--- a/notfair/src/app/(app)/[project]/goals/[agent]/page.tsx
+++ b/notfair/src/app/(app)/[project]/goals/[agent]/page.tsx
@@ -45,6 +45,8 @@ import {
type GoalSupportMetric,
} from "@/server/db/goal-support-metrics";
import { GoalSparkline } from "@/components/goal-sparkline";
+import { MetricMethodDialog } from "@/components/metric-method-dialog";
+import { timeUntil } from "@/lib/time-ago";
import { GoalMovesDialog } from "@/components/goal-moves-dialog";
import { type MoveRow } from "@/components/goal-moves";
import { GoalPrsDialog, type PrRow } from "@/components/goal-prs-dialog";
@@ -57,6 +59,18 @@ function fmtDate(iso: string | null): string {
return iso ? iso.slice(0, 10) : "—";
}
+/** Local wall-clock for a timestamp: "7:00 PM" today, "Jul 25, 9:00 AM" beyond. */
+function fmtClock(iso: string): string {
+ const date = new Date(iso);
+ const withinDay = Math.abs(date.getTime() - Date.now()) < 86_400_000;
+ return date.toLocaleString(
+ [],
+ withinDay
+ ? { hour: "numeric", minute: "2-digit" }
+ : { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" },
+ );
+}
+
const STATUS_CHIP: Record<Goal["status"], string> = {
@@ -302,9 +316,16 @@ function GoalRail({
<p className="m-0 mb-3 text-[12.5px] leading-relaxed">
Baseline <b className="tabular-nums">{formatMetric(goal.baseline_value)}</b>,
verified against{" "}
- <span className="font-mono text-[11px]">{goal.metric_source_key}</span>.
- The plan is agreed — the loop starts when you press START, and
- the first check runs immediately.
+ <span className="font-mono text-[11px]">{goal.metric_source_key}</span>{" "}
+ <MetricMethodDialog
+ name={goal.metric_name ?? "Metric"}
+ sourceKey={goal.metric_source_key}
+ sourceTool={goal.metric_source_tool}
+ argsJson={goal.metric_source_args_json}
+ direction={goal.metric_direction}
+ />
+ . The plan is agreed — the loop starts when you press START,
+ and the first check runs immediately.
</p>
<dl className="mb-3 grid grid-cols-2 gap-2 text-[12px]">
<RailStat k="Target" v={`${formatMetric(goal.target_value)}${goal.mode === "maintain" ? " (hold)" : ""}`} />
@@ -335,8 +356,15 @@ function GoalRail({
<>
<RailCard>
<div className="mb-1 flex items-baseline justify-between">
- <span className="text-[11px] text-[hsl(var(--notfair-ink-4))]">
- {goal.metric_name ?? "Metric"}
+ <span className="flex min-w-0 items-center gap-1.5 text-[11px] text-[hsl(var(--notfair-ink-4))]">
+ <span className="truncate">{goal.metric_name ?? "Metric"}</span>
+ <MetricMethodDialog
+ name={goal.metric_name ?? "Metric"}
+ sourceKey={goal.metric_source_key}
+ sourceTool={goal.metric_source_tool}
+ argsJson={goal.metric_source_args_json}
+ direction={goal.metric_direction}
+ />
</span>
{targetMet && (
<span className="ns-tag">
@@ -371,8 +399,12 @@ function GoalRail({
</div>
<p className="mt-1.5 mb-0 text-[11px] leading-relaxed text-[hsl(var(--notfair-ink-4))]">
{cadenceLabel(goal.cadence_cron)} · next check{" "}
- {goal.status === "active" ? fmtDate(goal.next_tick_at) : "—"} ·{" "}
- {goal.tick_count} check{goal.tick_count === 1 ? "" : "s"} so far
+ {goal.status === "active" && goal.next_tick_at
+ ? tickRunning
+ ? "running now"
+ : `${timeUntil(goal.next_tick_at)} (${fmtClock(goal.next_tick_at)})`
+ : "—"}{" "}
+ · {goal.tick_count} check{goal.tick_count === 1 ? "" : "s"} so far
{goal.spend_envelope_usd !== null &&
` · spent $${loggedSpendTotal(goal.id)} of $${goal.spend_envelope_usd}`}
</p>
@@ -397,7 +429,11 @@ function GoalRail({
<RailSection title="Checks" count={goal.tick_count}>
{checkRows.length === 0 ? (
<p className="m-0 text-[12px] text-[hsl(var(--notfair-ink-4))]">
- None yet — the first runs at {fmtDate(goal.next_tick_at)}.
+ None yet — the first runs{" "}
+ {goal.next_tick_at
+ ? `${timeUntil(goal.next_tick_at)} (${fmtClock(goal.next_tick_at)})`
+ : `at ${fmtDate(goal.next_tick_at)}`}
+ .
</p>
) : (
<GoalChecksList
@@ -426,7 +462,16 @@ function SupportMetricItem({ metric }: { metric: GoalSupportMetric }) {
return (
<li className="text-[12px] leading-snug">
<div className="flex items-baseline justify-between gap-2">
- <span className="text-[11px] text-[hsl(var(--notfair-ink-4))]">{metric.name}</span>
+ <span className="flex min-w-0 items-center gap-1.5 text-[11px] text-[hsl(var(--notfair-ink-4))]">
+ <span className="truncate">{metric.name}</span>
+ <MetricMethodDialog
+ name={metric.name}
+ sourceKey={metric.source_key}
+ sourceTool={metric.source_tool}
+ argsJson={metric.source_args_json}
+ direction={metric.direction}
+ />
+ </span>
<span className="font-medium tabular-nums">
{formatMetric(metric.current_value)}
<span className="ml-1.5 font-normal text-[11px] text-[hsl(var(--notfair-ink-4))]">
diff --git a/notfair/src/components/metric-method-dialog.tsx b/notfair/src/components/metric-method-dialog.tsx
new file mode 100644
index 00000000..0ba9bbd1
--- /dev/null
+++ b/notfair/src/components/metric-method-dialog.tsx
@@ -0,0 +1,119 @@
+"use client";
+
+import { useState } from "react";
+import { Info } from "lucide-react";
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogHeader,
+ DialogTitle,
+ DialogTrigger,
+} from "@/components/ui/dialog";
+
+/**
+ * "How is this measured?" — the metric's exact provenance: which
+ * connection, which tool, and the verbatim query/args the platform runs
+ * at every check. The value is never self-reported by the agent; this
+ * dialog is the proof.
+ */
+export function MetricMethodDialog({
+ name,
+ sourceKey,
+ sourceTool,
+ argsJson,
+ direction,
+}: {
+ name: string;
+ sourceKey: string | null;
+ sourceTool: string | null;
+ argsJson: string | null;
+ direction: "increase" | "decrease" | null;
+}) {
+ const [open, setOpen] = useState(false);
+
+ // The common shape is {"query": "<sql>"} — surface the query as code
+ // and any remaining args as pretty JSON. Fall back to the raw string.
+ let query: string | null = null;
+ let otherArgs: string | null = null;
+ if (argsJson) {
+ try {
+ const parsed = JSON.parse(argsJson) as Record<string, unknown>;
+ if (typeof parsed.query === "string") {
+ query = parsed.query;
+ const rest = Object.fromEntries(
+ Object.entries(parsed).filter(([k]) => k !== "query"),
+ );
+ if (Object.keys(rest).length > 0) otherArgs = JSON.stringify(rest, null, 2);
+ } else {
+ otherArgs = JSON.stringify(parsed, null, 2);
+ }
+ } catch {
+ otherArgs = argsJson;
+ }
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={setOpen}>
+ <DialogTrigger asChild>
+ <button
+ type="button"
+ aria-label={`How is “${name}” measured?`}
+ title="How is this measured?"
+ className="inline-flex shrink-0 items-center text-[hsl(var(--notfair-ink-4))] transition-colors hover:text-[hsl(var(--notfair-ink-2))]"
+ >
+ <Info className="size-3.5" />
+ </button>
+ </DialogTrigger>
+ <DialogContent className="max-h-[85vh] overflow-y-auto sm:max-w-xl">
+ <DialogHeader>
+ <DialogTitle className="text-[14px]">{name}</DialogTitle>
+ <DialogDescription>
+ Re-measured by the platform at every check, straight from the
+ source below — the agent never self-reports this number.
+ </DialogDescription>
+ </DialogHeader>
+ <dl className="m-0 grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5 text-[12.5px]">
+ <dt className="text-[hsl(var(--notfair-ink-4))]">Connection</dt>
+ <dd className="m-0 font-mono text-[12px]">{sourceKey ?? "—"}</dd>
+ <dt className="text-[hsl(var(--notfair-ink-4))]">Tool</dt>
+ <dd className="m-0 font-mono text-[12px]">{sourceTool ?? "—"}</dd>
+ <dt className="text-[hsl(var(--notfair-ink-4))]">Direction</dt>
+ <dd className="m-0">
+ {direction === "decrease"
+ ? "lower is better"
+ : direction === "increase"
+ ? "higher is better"
+ : "—"}
+ </dd>
+ </dl>
+ {query && (
+ <div>
+ <p className="m-0 mb-1.5 text-[11px] font-medium uppercase tracking-wide text-[hsl(var(--notfair-ink-4))]">
+ Query run at every check
+ </p>
+ <pre className="m-0 overflow-x-auto rounded-xl bg-[hsl(var(--notfair-surface-2))] p-3 text-[11.5px] leading-relaxed">
+ <code>{query}</code>
+ </pre>
+ </div>
+ )}
+ {otherArgs && (
+ <div>
+ <p className="m-0 mb-1.5 text-[11px] font-medium uppercase tracking-wide text-[hsl(var(--notfair-ink-4))]">
+ {query ? "Other arguments" : "Arguments"}
+ </p>
+ <pre className="m-0 overflow-x-auto rounded-xl bg-[hsl(var(--notfair-surface-2))] p-3 text-[11.5px] leading-relaxed">
+ <code>{otherArgs}</code>
+ </pre>
+ </div>
+ )}
+ {!query && !otherArgs && (
+ <p className="m-0 text-[12px] text-[hsl(var(--notfair-ink-4))]">
+ No measurement definition recorded — the metric is still being
+ set up in chat.
+ </p>
+ )}
+ </DialogContent>
+ </Dialog>
+ );
+}