@cursor/july 0.1.15 → 0.1.17

package/src/evals.ts

@@ -44,48 +44,116 @@
  *   ],
  * });
  * ```
+ *
+ * ## Severity: gates and scores
+ *
+ * Every assertion returns a chainable handle, so severity rides on the
+ * assertion instead of a separate thresholds map. Gates are hard (a miss fails
+ * the eval and `eval` exits non-zero); soft assertions are tracked scores that
+ * mark the eval `scored` and only fail the build under `--strict`:
+ *
+ * ```ts
+ * t.succeeded();                                        // gate (default)
+ * t.calledTool("get_weather").soft();                   // tracked, no gate
+ * t.check(t.reply, similarity("Sunny, 72F")).atLeast(0.8);
+ * t.judge.closedQA("cites a source").atLeast(0.6);      // LLM-graded
+ * ```
+ *
+ * Matchers narrow tool assertions (`{ input, output, status, count }` accept a
+ * literal, a RegExp, or a predicate), and each turn returned by `t.send(...)`
+ * carries the same vocabulary scoped to that turn.
  */
 
+import type {
+  EvalAssertionResult,
+  EvalAssertions,
+  EvalVerdict,
+} from "./evals/assertions.js";
+import type { Expectation } from "./evals/expect.js";
+import type { EvalJudge, EvalJudgeConfig } from "./evals/judge.js";
+import type { EvalReporter } from "./evals/results.js";
 import { normalizePositiveInt } from "./internal/bounded-int.js";
 import { brandDefinition } from "./internal/brand.js";
 import type { AgentCloudOptions, SessionEvent } from "./types.js";
 
-export type Expectation =
-  | { kind: "includes"; value: string | RegExp }
-  | { kind: "equals"; value: unknown }
-  | {
-      kind: "satisfies";
-      predicate: (value: unknown) => boolean;
-      label: string;
-    };
-
-export function includes(value: string | RegExp): Expectation {
-  return { kind: "includes", value };
-}
-
-export function equals(value: unknown): Expectation {
-  return { kind: "equals", value };
-}
-
-export function satisfies(
-  predicate: (value: unknown) => boolean,
-  label: string
-): Expectation {
-  return { kind: "satisfies", predicate, label };
-}
-
-export interface EvalAssertionResult {
-  name: string;
-  passed: boolean;
-  detail?: string;
-}
+// Assertion severity, the scoped assertion vocabulary, value assertion
+// builders, the judge surface, and result/reporter types are all part of the
+// authoring surface: one import (`@cursor/july/evals`) covers a whole eval file.
+export type {
+  EvalAssertionHandle,
+  EvalAssertionResult,
+  EvalAssertionSeverity,
+  EvalAssertions,
+  EvalVerdict,
+} from "./evals/assertions.js";
+export { computeVerdict, verdictFailsRun } from "./evals/assertions.js";
+export type { EvalSchemaLike, Expectation } from "./evals/expect.js";
+export {
+  equals,
+  includes,
+  matches,
+  normalizedSimilarity,
+  satisfies,
+  similarity,
+} from "./evals/expect.js";
+export type {
+  EvalJudge,
+  EvalJudgeCallOptions,
+  EvalJudgeConfig,
+  EvalJudgeGraderName,
+} from "./evals/judge.js";
+// A custom judge built on `t.judge.model` embeds the same attacker-controlled
+// agent output the built-in graders do, so it needs the same two protections.
+export {
+  EVAL_JUDGE_INJECTION_GUARD,
+  fenceUntrusted,
+} from "./evals/judge.js";
+export type {
+  EvalCountMatcher,
+  EvalEventMatcher,
+  EvalEventOrderMatcher,
+  EvalMatcher,
+  EvalSubagentMatcher,
+  EvalToolCallMatcher,
+  EvalToolCallStatus,
+} from "./evals/matchers.js";
+export type {
+  EvalReporter,
+  EvalReporterEvalInfo,
+  EvalReporterTarget,
+  EvalRunResult,
+  EvalRunSummary,
+} from "./evals/results.js";
+export type {
+  EvalInputRequestFact,
+  EvalRunFacts,
+  EvalSubagentFact,
+  EvalToolCallFact,
+} from "./evals/run-facts.js";
+export { deriveRunFacts } from "./evals/run-facts.js";
 
-export interface EvalTurnResult {
+/**
+ * One settled turn. Carries the same assertion vocabulary as `t`, narrowed to
+ * this turn's events, so an intermediate turn can be graded before the next
+ * `send` overwrites `t.reply`:
+ *
+ * ```ts
+ * const draft = await t.send("Draft the summary.");
+ * draft.calledTool("read_file");
+ * t.check(draft.message, includes("Summary"));
+ * ```
+ */
+export interface EvalTurnResult extends EvalAssertions {
   message: string;
   sessionId: string;
   events: SessionEvent[];
+  /** Tool names requested during this turn, in order. */
   toolCalls: string[];
   ok: boolean;
+  /** 1-based turn index within the case. */
+  index: number;
+  /** Throws when this turn failed. Only needed when later steps depend on it. */
+  expectOk(): EvalTurnResult;
 }
 
 export interface EvalSendOptions {
@@ -101,7 +169,15 @@ export interface EvalSendOptions {
   cloud?: AgentCloudOptions;
 }
 
-export interface EvalTestContext {
+/**
+ * The eval driver and assertion surface.
+ *
+ * `t` both drives the agent and grades it. Assertions on `t` read the whole run
+ * once `test` finishes; assertions on the turn returned by `t.send(...)` read
+ * only that turn. Recorded assertions never throw, so one run reports every
+ * failure rather than dying on the first.
+ */
+export interface EvalTestContext extends EvalAssertions {
   /** Send a turn and wait until the session parks (or fails). */
   send(message: string, options?: EvalSendOptions): Promise<EvalTurnResult>;
   /** Last assistant text, or null before the first send. */
@@ -109,6 +185,8 @@ export interface EvalTestContext {
   readonly sessionId: string | undefined;
   /** All events captured so far across turns. */
   readonly events: SessionEvent[];
+  /** Turns settled so far, oldest first. */
+  readonly turns: readonly EvalTurnResult[];
   /**
    * 1-based index of this run when {@link EvalConfig.iterations} /
    * {@link EvalDatapoint.iterations} expands a datapoint. Always `1` when
@@ -117,16 +195,25 @@ export interface EvalTestContext {
   readonly iteration: number;
   /** Total iterations for this datapoint (default `1`). */
   readonly iterations: number;
-  /** Gate: run did not fail. */
-  succeeded(): void;
-  /** Gate: at least one completed call to `name`. */
-  calledTool(name: string): void;
-  /** Gate: no call to `name`. */
-  notCalledTool(name: string): void;
-  /** Gate: joined assistant text matches. */
-  messageIncludes(token: string | RegExp): void;
-  /** Gate a value with an {@link Expectation} builder. */
-  check(value: unknown, assertion: Expectation): void;
+  /** Aborts when the case hits its timeout. */
+  readonly signal: AbortSignal;
+  /**
+   * LLM-as-judge assertions. Soft by default (tracked, never fatal); add a bar
+   * with `.atLeast(0.7)` or promote with `.gate(0.8)`. Requires a judge model
+   * from `defineEvalConfig({ judge })`, `defineEval({ judge })`, or the call.
+   */
+  readonly judge: EvalJudge;
+  /**
+   * Record a gate that must pass before the script can safely continue.
+   * Returns `value` when it passes and stops the test body when it does not,
+   * without adding a duplicate execution error.
+   */
+  require<T>(value: T, assertion: Expectation): Promise<T>;
+  /**
+   * End the case as skipped. Skipped cases are reported separately and never
+   * change the exit code. Call it before sending messages.
+   */
+  skip(reason: string): never;
   /** Debug line (surfaced under `agent-serve eval --verbose`). */
   log(message: string): void;
   /**
@@ -158,6 +245,12 @@ export interface EvalDatapoint {
    * concurrent case.
    */
   iterations?: number;
+  /** Free-form data carried onto the result and every reporter. */
+  metadata?: Record<string, unknown>;
+  /** Judge model for this datapoint (overrides `evals.config.ts`). */
+  judge?: EvalJudgeConfig;
+  /** Destinations for just this datapoint, in addition to config reporters. */
+  reporters?: EvalReporter[];
   test: (t: EvalTestContext) => Promise<void>;
 }
 
@@ -174,6 +267,12 @@ export interface EvalConfig {
    * Case-level {@link EvalDatapoint.iterations} overrides this.
    */
   iterations?: number;
+  /** Free-form data carried onto every result in this file and to reporters. */
+  metadata?: Record<string, unknown>;
+  /** Judge model for this file (overrides `evals.config.ts`). */
+  judge?: EvalJudgeConfig;
+  /** Destinations for this file, in addition to config reporters. */
+  reporters?: EvalReporter[];
   /** Single-datapoint shorthand. Case id = file path under `evals/`. */
   test?: (t: EvalTestContext) => Promise<void>;
   /** Multiple datapoints in this file. Each id = `<fileId>/<case.id>`. */
@@ -189,6 +288,9 @@ export interface EvalCaseDefinition {
   iterations?: number;
   /** 1-based iteration index for this expanded runnable case. */
   iteration?: number;
+  metadata?: Record<string, unknown>;
+  judge?: EvalJudgeConfig;
+  reporters?: EvalReporter[];
   test: (t: EvalTestContext) => Promise<void>;
   readonly __agentServe: "eval";
 }
@@ -275,12 +377,19 @@ export function expandEvalDefinition(
       const iterations = normalizeEvalIterations(
         datapoint.iterations ?? definition.iterations ?? 1
       );
+      const metadata =
+        datapoint.metadata === undefined && definition.metadata === undefined
+          ? undefined
+          : { ...definition.metadata, ...datapoint.metadata };
       return expandIterations({
         baseId: `${fileId}/${datapoint.id}`,
         description,
         tags: datapoint.tags ?? definition.tags,
         timeoutMs,
         iterations,
+        metadata,
+        judge: datapoint.judge ?? definition.judge,
+        reporters: mergeReporters(definition.reporters, datapoint.reporters),
         test: datapoint.test,
       });
     });
@@ -295,16 +404,36 @@ export function expandEvalDefinition(
     tags: definition.tags,
     timeoutMs: definition.timeoutMs,
     iterations,
+    metadata: definition.metadata,
+    judge: definition.judge,
+    reporters: definition.reporters,
     test: definition.test,
   });
 }
 
+/** Union file-level and case-level reporters, keeping each instance once. */
+function mergeReporters(
+  fileLevel: EvalReporter[] | undefined,
+  caseLevel: EvalReporter[] | undefined
+): EvalReporter[] | undefined {
+  if (fileLevel === undefined) {
+    return caseLevel;
+  }
+  if (caseLevel === undefined) {
+    return fileLevel;
+  }
+  return [...new Set([...fileLevel, ...caseLevel])];
+}
+
 function expandIterations(args: {
   baseId: string;
   description?: string;
   tags?: string[];
   timeoutMs?: number;
   iterations: number;
+  metadata?: Record<string, unknown>;
+  judge?: EvalJudgeConfig;
+  reporters?: EvalReporter[];
   test: (t: EvalTestContext) => Promise<void>;
 }): Array<{ id: string; definition: EvalCaseDefinition }> {
   const out: Array<{ id: string; definition: EvalCaseDefinition }> = [];
@@ -321,6 +450,9 @@ function expandIterations(args: {
         ...(description !== undefined ? { description } : {}),
         ...(args.tags !== undefined ? { tags: args.tags } : {}),
         ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
+        metadata: args.metadata,
+        judge: args.judge,
+        reporters: args.reporters,
         iterations: args.iterations,
         iteration,
         test: args.test,
@@ -340,6 +472,50 @@ export function matchesEvalIdFilter(caseId: string, filter: string): boolean {
   return caseId === filter || caseId.startsWith(`${filter}/`);
 }
 
+/**
+ * Tag for suite-aggregator datapoints that wait on sibling cases from the
+ * same eval file (e.g. `deepsec-recall/overall`). Selecting a summary case
+ * alone expands the batch to the whole file via
+ * {@link expandSummarySuiteSelection}.
+ */
+export const EVAL_SUMMARY_TAG = "summary";
+
+/** True when `tags` marks a suite-aggregator case. */
+export function isEvalSummaryCase(
+  tags: readonly string[] | undefined
+): boolean {
+  return tags?.includes(EVAL_SUMMARY_TAG) ?? false;
+}
+
+/**
+ * If `selected` includes any summary-tagged suite aggregator, pull in every
+ * other datapoint from the same `fileId` so the aggregator is not run alone.
+ * Preserves discovery order from `all`.
+ */
+export function expandSummarySuiteSelection<
+  T extends { id: string; fileId: string },
+>(
+  all: readonly T[],
+  selected: readonly T[],
+  isSummary: (item: T) => boolean
+): T[] {
+  const fileIdsNeedingSuite = new Set(
+    selected.filter((item) => isSummary(item)).map((item) => item.fileId)
+  );
+  if (fileIdsNeedingSuite.size === 0) {
+    return [...selected];
+  }
+  const selectedIds = new Set(selected.map((item) => item.id));
+  const extras = all.filter(
+    (item) => fileIdsNeedingSuite.has(item.fileId) && !selectedIds.has(item.id)
+  );
+  if (extras.length === 0) {
+    return [...selected];
+  }
+  const want = new Set([...selectedIds, ...extras.map((item) => item.id)]);
+  return all.filter((item) => want.has(item.id));
+}
+
 /**
  * Hard ceiling for concurrent eval cases.
  *
@@ -365,6 +541,10 @@ export interface EvalCaseSnapshot {
   tags?: string[];
   status: EvalCaseRunStatus;
   ok?: boolean;
+  /** Full grade, including `scored` (soft threshold miss) and `skipped`. */
+  verdict?: EvalVerdict;
+  /** Reason passed to `t.skip(...)`. */
+  skipReason?: string;
   assertions?: EvalAssertionResult[];
   sessionId?: string;
   durationMs?: number;
@@ -372,6 +552,8 @@ export interface EvalCaseSnapshot {
   logs?: string[];
   /** Structured scores from {@link EvalTestContext.metric}. */
   metrics?: Record<string, string | number>;
+  /** Author-supplied metadata from `defineEval({ metadata })`. */
+  metadata?: Record<string, unknown>;
   inputs?: string[];
   finalText?: string;
   tools?: string[];
@@ -390,7 +572,19 @@ export interface EvalRunSnapshot {
   startedAt: string;
   finishedAt?: string;
   error?: string;
-  summary: { passed: number; failed: number; total: number; done: number };
+  summary: {
+    passed: number;
+    failed: number;
+    /**
+     * Cases that only missed a soft threshold (fatal only under `--strict`).
+     * Optional: a batch persisted by an older serve process has no such count.
+     */
+    scored?: number;
+    /** Cases ended by `t.skip(...)`; they never change the exit code. */
+    skipped?: number;
+    total: number;
+    done: number;
+  };
   cases: EvalCaseSnapshot[];
   config: {
     maxConcurrency?: number;
@@ -453,6 +647,17 @@ export interface EvalConfigFile {
    * request limits.
    */
   maxConcurrency: number;
+  /**
+   * Default judge model for `t.judge.*` across this tree. Optional: a tree of
+   * fully deterministic evals never needs one.
+   */
+  judge?: EvalJudgeConfig;
+  /**
+   * Destinations that observe **every** case in the run — the right place for a
+   * shared one, so you do not repeat it in each eval file. `--skip-report`
+   * suppresses them for a local iteration loop.
+   */
+  reporters?: EvalReporter[];
   /**
    * Optional. Max batches kept in the **playground / `/v1/dev/evals*`**
    * history window (in-memory, and pruned from the `defineStorage` evals
@@ -479,6 +684,8 @@ export function defineEvalConfig(config: EvalConfigFile): EvalConfigFile {
     maxPlaygroundRuns: normalizeEvalMaxPlaygroundRuns(
       config.maxPlaygroundRuns ?? EVAL_DEFAULT_MAX_PLAYGROUND_RUNS
     ),
+    judge: config.judge,
+    reporters: config.reporters,
   };
 }
 

package/src/index.ts

@@ -124,12 +124,14 @@ export {
 export { defineTool } from "./tools.js";
 export type * from "./types.js";
 export {
+  cursorAccountServersHasMixedWildcard,
   DEFAULT_MODEL,
   DIRECT_TOOL_CALL_CHANNEL_ID,
   isCursorAccountTransport,
   isPeerConnectionTransport,
   isSymbolicConnectionTransport,
   MAX_RUNNING_TURNS_LIMIT,
+  normalizeCursorAccountServers,
 } from "./types.js";
 
 /**

package/src/internal/cli-ax.ts

@@ -10,7 +10,13 @@
 import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import type { EvalRunSnapshot } from "../evals.js";
+import { Artifacts, JUnit } from "../evals/reporters.js";
+import type {
+  EvalAssertionResult,
+  EvalReporter,
+  EvalRunSnapshot,
+  EvalVerdict,
+} from "../evals.js";
 import { serve } from "../index.js";
 import type { AgentServeHandle } from "../types.js";
 import { lookupSessionContinuation, runChat } from "./chat-client.js";
@@ -96,6 +102,19 @@ export interface AxCliOptions {
   tags?: string[];
   /** Eval ids / path prefixes. */
   evalIds?: string[];
+  /** `eval`: a soft threshold miss (`scored`) also fails the exit code. */
+  strict?: boolean;
+  /** `eval`: write JUnit XML to this path. */
+  junit?: string;
+  /**
+   * `eval`: run-artifact directory. Defaults to a timestamped directory under
+   * `<dir>/.agent-serve/evals/`; `false` disables artifacts entirely.
+   */
+  artifacts?: string | false;
+  /** `eval`: skip reporters declared in `evals.config.ts` and eval files. */
+  skipReport?: boolean;
+  /** `eval`: override `evals.config.ts` `maxConcurrency`. */
+  maxConcurrency?: number;
   /** Scaffold target directory for `init`. */
   initTarget?: string;
   /** Tool name for `call`. */
@@ -839,6 +858,7 @@ export async function cmdEval(options: AxCliOptions): Promise<number> {
     // batch lands in playground history and defineStorage evals (when set).
     if (mode === "local") {
       const progress = stream ? createStreamProgress() : undefined;
+      const artifactsDir = resolveEvalArtifactsDir(projectRoot, options);
       try {
         const results = await runDiscoveredEvals({
           projectRoot,
@@ -846,6 +866,11 @@ export async function cmdEval(options: AxCliOptions): Promise<number> {
           filterIds,
           tags,
           timeoutMs: options.timeoutMs,
+          maxConcurrency: options.maxConcurrency,
+          strict: options.strict === true,
+          skipReport: options.skipReport === true,
+          reporters: buildCliEvalReporters(options, artifactsDir),
+          target: { baseUrl: target.agentUrl, mode: "local" },
           bearerToken: options.bearerToken,
           headers: target.headers,
           verbose: Boolean(options.verbose) || stream,
@@ -856,7 +881,7 @@ export async function cmdEval(options: AxCliOptions): Promise<number> {
           process.stderr.write("No matching evals found.\n");
           return 2;
         }
-        return printEvalResults(results, options);
+        return printEvalResults(results, options, undefined, artifactsDir);
       } finally {
         progress?.close();
       }
@@ -1359,6 +1384,53 @@ function createRemoteEvalProgress(
   };
 }
 
+/**
+ * Where a local run writes its artifacts.
+ *
+ * Defaults to a timestamped directory under the project's gitignored
+ * `.agent-serve/evals/`, so the full story of a failure is always on disk
+ * without the eval author opting in. `--no-artifacts` turns it off.
+ */
+export function resolveEvalArtifactsDir(
+  projectRoot: string,
+  options: Pick<AxCliOptions, "artifacts">
+): string | undefined {
+  if (options.artifacts === false) {
+    return undefined;
+  }
+  if (typeof options.artifacts === "string" && options.artifacts !== "") {
+    return resolve(options.artifacts);
+  }
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return join(projectRoot, ".agent-serve", "evals", stamp);
+}
+
+/** JUnit / artifacts reporters requested via CLI flags. */
+function buildCliEvalReporters(
+  options: AxCliOptions,
+  artifactsDir: string | undefined
+): EvalReporter[] {
+  const reporters: EvalReporter[] = [];
+  if (artifactsDir !== undefined) {
+    reporters.push(Artifacts({ dir: artifactsDir }));
+  }
+  if (options.junit !== undefined && options.junit !== "") {
+    reporters.push(JUnit({ filePath: options.junit }));
+  }
+  return reporters;
+}
+
+function evalVerdictOf(result: EvalRunResult): EvalVerdict {
+  return result.verdict ?? (result.ok ? "passed" : "failed");
+}
+
+const EVAL_VERDICT_LABEL: Record<EvalVerdict, string> = {
+  passed: "PASS",
+  failed: "FAIL",
+  scored: "SCORED",
+  skipped: "SKIP",
+};
+
 function printEvalResults(
   results: EvalRunResult[],
   options: AxCliOptions,
@@ -1366,12 +1438,17 @@ function printEvalResults(
     runId?: string;
     status?: EvalRunSnapshot["status"];
     error?: string;
-  }
+  },
+  artifactsDir?: string
 ): number {
-  const passed = results.filter((r) => r.ok).length;
-  const failed = results.length - passed;
+  const strict = options.strict === true;
+  const counts = { passed: 0, failed: 0, scored: 0, skipped: 0 };
+  for (const result of results) {
+    counts[evalVerdictOf(result)]++;
+  }
   const batchFailed = batch?.status === "failed";
-  const ok = failed === 0 && !batchFailed;
+  const ok =
+    counts.failed === 0 && !(strict && counts.scored > 0) && !batchFailed;
 
   if (batch?.error !== undefined && batch.error !== "" && !options.json) {
     // Always surface harness-level failures (not only --verbose).
@@ -1383,9 +1460,13 @@ function printEvalResults(
       JSON.stringify(
         {
           ok,
-          passed,
-          failed,
+          passed: counts.passed,
+          failed: counts.failed,
+          scored: counts.scored,
+          skipped: counts.skipped,
+          strict,
           results,
+          ...(artifactsDir === undefined ? {} : { artifactsDir }),
           ...(batch?.runId === undefined ? {} : { runId: batch.runId }),
           ...(batch?.status === undefined ? {} : { status: batch.status }),
           ...(batch?.error === undefined || batch.error === ""
@@ -1398,19 +1479,19 @@ function printEvalResults(
     );
   } else {
     for (const r of results) {
+      const verdict = evalVerdictOf(r);
       process.stdout.write(
-        `${r.ok ? "PASS" : "FAIL"}  ${r.id} (${(r.durationMs / 1000).toFixed(1)}s)`
+        `${EVAL_VERDICT_LABEL[verdict]}  ${r.id} (${(r.durationMs / 1000).toFixed(1)}s)`
       );
       if (r.description !== undefined) {
         process.stdout.write(` — ${r.description}`);
       }
       process.stdout.write("\n");
+      if (r.skipReason !== undefined) {
+        process.stdout.write(`  skipped: ${r.skipReason}\n`);
+      }
       for (const a of r.assertions) {
-        process.stdout.write(
-          `  ${a.passed ? "✓" : "✗"} ${a.name}${
-            a.detail !== undefined ? ` (${a.detail})` : ""
-          }\n`
-        );
+        process.stdout.write(`  ${formatEvalAssertionLine(a)}\n`);
       }
       for (const [name, value] of Object.entries(r.metrics ?? {})) {
         process.stdout.write(`  metric ${name}=${String(value)}\n`);
@@ -1427,13 +1508,51 @@ function printEvalResults(
         );
       }
     }
+    const extra: string[] = [];
+    if (counts.scored > 0) {
+      extra.push(
+        `${counts.scored} scored${strict ? " (fatal: --strict)" : ""}`
+      );
+    }
+    if (counts.skipped > 0) {
+      extra.push(`${counts.skipped} skipped`);
+    }
     process.stdout.write(
-      `\n${passed} passed, ${failed} failed, ${results.length} total\n`
+      `\n${counts.passed} passed, ${counts.failed} failed${
+        extra.length === 0 ? "" : `, ${extra.join(", ")}`
+      }, ${results.length} total\n`
     );
+    if (artifactsDir !== undefined) {
+      process.stdout.write(`artifacts: ${artifactsDir}\n`);
+    }
   }
   return ok ? 0 : 1;
 }
 
+/**
+ * One assertion line. Soft assertions read `~` rather than `✗` when they miss,
+ * so a tracked score is visibly different from a failed gate.
+ */
+export function formatEvalAssertionLine(
+  assertion: EvalAssertionResult
+): string {
+  const soft = (assertion.severity ?? "gate") === "soft";
+  const mark = assertion.passed ? "✓" : soft ? "~" : "✗";
+  const parts: string[] = [];
+  if (assertion.score !== undefined) {
+    parts.push(
+      `score=${assertion.score.toFixed(3)}${
+        assertion.threshold === undefined ? "" : ` >= ${assertion.threshold}`
+      }`
+    );
+  }
+  if (assertion.detail !== undefined) {
+    parts.push(assertion.detail);
+  }
+  const suffix = parts.length === 0 ? "" : ` (${parts.join(", ")})`;
+  return `${mark} ${assertion.name}${soft ? " [soft]" : ""}${suffix}`;
+}
+
 /**
  * `logs` — follow deploy progress (`--prod`) then runtime agent logs.
  * Local / `--url` tails `/v1/logs` only.