feat(autoresearch): report and render the metric's unit with every dashboard value

The report protocol gains a structured unit: line (e.g. kB, ms, %) and
the name: guidance drops "with units", so the dashboard title stays a
clean label while every value carries the unit. The first report with a
unit sets run.metricUnit (first-wins, persisted, like the name); units
longer than 16 chars are ignored as prose, and unitless metrics render
bare as before.

Rendered via a shared withMetricUnit helper (space-separated, % hugs the
number) on: the Best/Last/Target stat cards, the chart's y-axis extremes,
target label and point tooltips, and the iteration table's Value and
delta columns. Continuation prompts include the unit in the history block
too, keeping the agent grounded in the units it reports.

Tests: 136 autoresearch core tests (unit parsing, too-long-unit guard,
first-unit-wins adoption, unit in history prompts, protocol example);
full core/ui/app suites green.

Generated-By: PostHog Code
Task-Id: 41d083af-f0ef-49c1-bce2-9d4a34046981

Author: fercgomes

packages/core/src/autoresearch/autoresearch.test.ts

@@ -247,6 +247,7 @@ function makeRun(
     config: { ...config, ...configOverrides },
     status: "running",
     metricName: null,
+    metricUnit: null,
     phase: null,
     originalModel: null,
     originalEffort: null,
@@ -526,6 +527,18 @@ describe("AutoresearchService", () => {
       expect(activeRun().metricName).toBe("bundle size (kB)");
     });
 
+    it("adopts the metric unit from the first report that carries one", () => {
+      service.startRun(baseConfig);
+      runTurn(
+        "```autoresearch\nmetric: 412\nname: bundle size\nunit: kB\nsummary: baseline\n```",
+      );
+      expect(activeRun().metricUnit).toBe("kB");
+
+      // First unit wins, like the name — a stable unit keeps values readable.
+      runTurn("```autoresearch\nmetric: 400000\nunit: bytes\n```");
+      expect(activeRun().metricUnit).toBe("kB");
+    });
+
     it("runs unnamed until a report carries a name", () => {
       service.startRun(baseConfig);
       runTurn(reportText(10));

packages/core/src/autoresearch/autoresearch.ts

@@ -148,6 +148,7 @@ export class AutoresearchService {
       config,
       status: "running",
       metricName: null,
+      metricUnit: null,
       phase: null,
       originalModel: session ? currentSessionModel(session) : null,
       originalEffort: session ? currentSessionEffort(session) : null,
@@ -450,11 +451,16 @@ export class AutoresearchService {
     // the recovery backoff from scratch.
     this.recoveryAttempts.delete(run.id);
     this.recordIteration(run, report);
-    if (report.name) {
+    if (report.name || report.unit) {
       const current = autoresearchStore.getState().runs[run.id];
       // First named report wins; a stable label keeps the dashboard steady.
-      if (current && current.metricName === null) {
-        autoresearchStoreActions.setMetricName(run.id, report.name);
+      if (current) {
+        if (report.name && current.metricName === null) {
+          autoresearchStoreActions.setMetricName(run.id, report.name);
+        }
+        if (report.unit && current.metricUnit === null) {
+          autoresearchStoreActions.setMetricUnit(run.id, report.unit);
+        }
       }
     }
     this.persist(run.id);

packages/core/src/autoresearch/autoresearchStore.ts

@@ -55,6 +55,11 @@ export const autoresearchStoreActions = {
     updateRun(runId, (run) => ({ ...run, metricName }));
   },
 
+  /** Record the metric unit the agent chose in its reports. */
+  setMetricUnit(runId: string, metricUnit: string): void {
+    updateRun(runId, (run) => ({ ...run, metricUnit }));
+  },
+
   setPhase(runId: string, phase: AutoresearchPhase | null): void {
     updateRun(runId, (run) => ({ ...run, phase }));
   },

packages/core/src/autoresearch/prompts.test.ts

@@ -50,6 +50,7 @@ function makeRun(
     config: makeConfig(configOverrides),
     status: "running",
     metricName: "requests per second",
+    metricUnit: null,
     phase: null,
     originalModel: null,
     originalEffort: null,
@@ -74,6 +75,7 @@ describe("parseMetricReport", () => {
     expect(parseMetricReport(text)).toEqual({
       value: 1234.5,
       name: null,
+      unit: null,
       summary: "swapped JSON parser",
     });
   });
@@ -82,6 +84,7 @@ describe("parseMetricReport", () => {
     expect(parseMetricReport(report("42"))).toEqual({
       value: 42,
       name: null,
+      unit: null,
       summary: null,
     });
   });
@@ -99,6 +102,7 @@ describe("parseMetricReport", () => {
     expect(parseMetricReport(text)).toEqual({
       value: 2,
       name: null,
+      unit: null,
       summary: "final",
     });
   });
@@ -108,6 +112,7 @@ describe("parseMetricReport", () => {
     expect(parseMetricReport(text)).toEqual({
       value: 7,
       name: null,
+      unit: null,
       summary: "good",
     });
   });
@@ -125,6 +130,7 @@ describe("parseMetricReport", () => {
     expect(parseMetricReport(text)).toEqual({
       value: 99,
       name: null,
+      unit: null,
       summary: "tidy",
     });
   });
@@ -306,6 +312,42 @@ describe("buildResumePrompt", () => {
   });
 });
 
+describe("unit parsing and rendering", () => {
+  it("parses the unit line", () => {
+    const text =
+      "```autoresearch\nmetric: 412\nname: bundle size\nunit: kB\nsummary: trimmed deps\n```";
+    expect(parseMetricReport(text)).toEqual({
+      value: 412,
+      name: "bundle size",
+      unit: "kB",
+      summary: "trimmed deps",
+    });
+  });
+
+  it("ignores a unit that is too long to be a unit", () => {
+    const text =
+      "```autoresearch\nmetric: 5\nunit: kilobytes of gzipped production javascript\n```";
+    expect(parseMetricReport(text)?.unit).toBeNull();
+  });
+
+  it("includes the unit in continuation history once known", () => {
+    const run = {
+      ...makeRun([makeIteration(1, 100, "baseline")]),
+      metricUnit: "ms",
+    };
+    const prompt = buildContinuationPrompt(run);
+    expect(prompt).toContain("- Iteration 1: 100 ms — baseline");
+    expect(prompt).toContain("Best so far: 100 ms (iteration 1)");
+    expect(prompt).toContain("Last: 100 ms");
+  });
+
+  it("mentions the unit line in the protocol example", () => {
+    expect(buildKickoffPreamble(makeConfig())).toContain(
+      "unit: <the metric's unit",
+    );
+  });
+});
+
 describe("countPromptRequests", () => {
   it("counts only session/prompt requests", () => {
     expect(countPromptRequests([])).toBe(0);

packages/core/src/autoresearch/prompts.ts

@@ -17,7 +17,8 @@ import { computeBest } from "./stats";
 const REPORT_BLOCK_EXAMPLE = [
   "```autoresearch",
   "metric: <number>",
-  "name: <short metric label with units, e.g. bundle size (kB) — keep it identical every time>",
+  "name: <short metric label, e.g. bundle size — keep it identical every time>",
+  "unit: <the metric's unit, e.g. kB, ms, % — omit for unitless counts>",
   "summary: <one line describing what you changed>",
   "```",
 ].join("\n");
@@ -71,19 +72,20 @@ function historyBlock(run: AutoresearchRun): string {
   const { config, iterations } = run;
   const best = computeBest(iterations, config.direction);
   const last = iterations[iterations.length - 1];
+  const unit = run.metricUnit ? ` ${run.metricUnit}` : "";
 
   const recent = iterations
     .slice(-5)
     .map(
       (iteration) =>
-        `- Iteration ${iteration.index}: ${iteration.value}${iteration.summary ? ` — ${iteration.summary}` : ""}`,
+        `- Iteration ${iteration.index}: ${iteration.value}${unit}${iteration.summary ? ` — ${iteration.summary}` : ""}`,
     )
     .join("\n");
 
   return `Recent iterations:
 ${recent}
 
-Best so far: ${best ? `${best.value} (iteration ${best.index})` : "none"}. Last: ${last ? last.value : "none"}.${targetLine(config)}`;
+Best so far: ${best ? `${best.value}${unit} (iteration ${best.index})` : "none"}. Last: ${last ? `${last.value}${unit}` : "none"}.${targetLine(config)}`;
 }
 
 export function buildContinuationPrompt(run: AutoresearchRun): string {
@@ -179,9 +181,13 @@ export function parseMetricReport(text: string): AutoresearchReport | null {
   return report;
 }
 
+/** Anything longer is prose, not a unit; ignore it rather than blow up the UI. */
+const MAX_UNIT_LENGTH = 16;
+
 function parseReportBody(body: string): AutoresearchReport | null {
   let value: number | null = null;
   let name: string | null = null;
+  let unit: string | null = null;
   let summary: string | null = null;
   for (const line of body.split("\n")) {
     const separator = line.indexOf(":");
@@ -193,11 +199,17 @@ function parseReportBody(body: string): AutoresearchReport | null {
       if (Number.isFinite(numeric)) value = numeric;
     } else if (key === "name" && raw.length > 0) {
       name = raw;
+    } else if (
+      key === "unit" &&
+      raw.length > 0 &&
+      raw.length <= MAX_UNIT_LENGTH
+    ) {
+      unit = raw;
     } else if (key === "summary" && raw.length > 0) {
       summary = raw;
     }
   }
-  return value === null ? null : { value, name, summary };
+  return value === null ? null : { value, name, unit, summary };
 }
 
 interface AgentMessageChunkUpdate {

packages/core/src/autoresearch/schemas.ts

@@ -118,6 +118,11 @@ export const autoresearchRunSchema = z.object({
    * "bundle size (kB)". Null until the first named report arrives.
    */
   metricName: z.string().nullable().default(null),
+  /**
+   * The metric's unit as reported by the agent (the `unit:` line), e.g.
+   * "kB", "ms", "%". Rendered after every value; null for unitless counts.
+   */
+  metricUnit: z.string().nullable().default(null),
   phase: autoresearchPhaseSchema.nullable().default(null),
   /**
    * The session model/effort selected when the run started, captured so
@@ -167,7 +172,9 @@ export function parseStoredAutoresearchRun(
 /** A metric report parsed from the agent's reply. */
 export interface AutoresearchReport {
   value: number;
-  /** The agent's short label for the metric, e.g. "bundle size (kB)". */
+  /** The agent's short label for the metric, e.g. "bundle size". */
   name: string | null;
+  /** The metric's unit, e.g. "kB", "ms", "%"; null for unitless counts. */
+  unit: string | null;
   summary: string | null;
 }

packages/core/src/autoresearch/stats.test.ts

@@ -45,6 +45,7 @@ function makeRun(overrides: {
     },
     status: "running",
     metricName: "score",
+    metricUnit: null,
     phase: null,
     originalModel: null,
     originalEffort: null,

packages/ui/src/features/autoresearch/AutoresearchPanel.tsx

@@ -24,6 +24,7 @@ import { usePendingPermissionsForTask } from "../sessions/useSession";
 import { AutoresearchConfigDialog } from "./AutoresearchConfigDialog";
 import { IterationsTable } from "./IterationsTable";
 import { MetricChart } from "./MetricChart";
+import { withMetricUnit } from "./metricFormat";
 import {
   type AutoresearchModelOption,
   stageValueLabel,
@@ -174,10 +175,12 @@ export function AutoresearchPanel({ taskId }: AutoresearchPanelProps) {
           direction={selectedRun.config.direction}
           targetValue={selectedRun.config.targetValue}
           metricName={selectedRun.metricName ?? "the metric"}
+          unit={selectedRun.metricUnit}
         />
         <IterationsTable
           iterations={selectedRun.iterations}
           direction={selectedRun.config.direction}
+          unit={selectedRun.metricUnit}
         />
       </Flex>
       <AutoresearchConfigDialog
@@ -377,6 +380,7 @@ function PendingPermissionNotice({
 
 function RunStats({ run }: { run: AutoresearchRun }) {
   const summary = useMemo(() => summarizeRun(run), [run]);
+  const unit = run.metricUnit;
 
   return (
     <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
@@ -385,7 +389,7 @@ function RunStats({ run }: { run: AutoresearchRun }) {
         value={
           summary.best ? (
             <>
-              {numberFormat.format(summary.best.value)}
+              {withMetricUnit(numberFormat.format(summary.best.value), unit)}
               <Text size="1" color="gray">
                 {" "}
                 (iter {summary.best.index})
@@ -398,7 +402,11 @@ function RunStats({ run }: { run: AutoresearchRun }) {
       />
       <StatCard
         label="Last"
-        value={summary.last ? numberFormat.format(summary.last.value) : "—"}
+        value={
+          summary.last
+            ? withMetricUnit(numberFormat.format(summary.last.value), unit)
+            : "—"
+        }
       />
       <StatCard
         label="Iterations"
@@ -409,7 +417,7 @@ function RunStats({ run }: { run: AutoresearchRun }) {
         value={
           run.config.targetValue === null
             ? "—"
-            : numberFormat.format(run.config.targetValue)
+            : withMetricUnit(numberFormat.format(run.config.targetValue), unit)
         }
       />
     </div>

packages/ui/src/features/autoresearch/IterationsTable.tsx

@@ -5,10 +5,12 @@ import type {
 import { computeBest, isImprovement } from "@posthog/core/autoresearch/stats";
 import { Badge, Table, Text } from "@radix-ui/themes";
 import { useMemo } from "react";
+import { withMetricUnit } from "./metricFormat";
 
 interface IterationsTableProps {
   iterations: AutoresearchIteration[];
   direction: AutoresearchDirection;
+  unit: string | null;
 }
 
 const numberFormat = new Intl.NumberFormat("en-US", {
@@ -31,6 +33,7 @@ function deltaColor(
 export function IterationsTable({
   iterations,
   direction,
+  unit,
 }: IterationsTableProps) {
   const best = useMemo(
     () => computeBest(iterations, direction),
@@ -63,7 +66,7 @@ export function IterationsTable({
             <Table.Cell>{iteration.index}</Table.Cell>
             <Table.Cell>
               <span className="flex items-center gap-1 tabular-nums">
-                {numberFormat.format(iteration.value)}
+                {withMetricUnit(numberFormat.format(iteration.value), unit)}
                 {best?.index === iteration.index && (
                   <Badge color="amber" size="1">
                     best
@@ -79,7 +82,10 @@ export function IterationsTable({
               >
                 {iteration.delta === null
                   ? "—"
-                  : `${iteration.delta > 0 ? "+" : ""}${numberFormat.format(iteration.delta)}`}
+                  : withMetricUnit(
+                      `${iteration.delta > 0 ? "+" : ""}${numberFormat.format(iteration.delta)}`,
+                      unit,
+                    )}
               </Text>
             </Table.Cell>
             <Table.Cell className="max-w-[320px]">