dsh-model-everything 0.2.0 → 0.4.0

package/src/export-tool.ts

@@ -1,81 +1,90 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from './json-value.js'
-import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, validateModel, verdictOf } from './engine.js'
-import { ExportError, exportModel, type ExportFormat } from './exporters.js'
-import { renderReportText } from './report-view.js'
-
-/** The model hash of an export's input, when the input validates (the success path always does). */
-function exportHashes(model: unknown): { hashSpec: typeof DEFAULT_HASH_SPEC; modelHash?: string } {
-  const validation = validateModel(model)
-  return validation.ok
-    ? { hashSpec: DEFAULT_HASH_SPEC, modelHash: modelHash(validation.model) }
-    : { hashSpec: DEFAULT_HASH_SPEC }
-}
-
-export const EXPORT_TOOL_NAME = 'model_export'
-
-/**
- * DSH tool wrapping the external-tool exporters: turn a LogicModelV1 machine into
- * native input for the tool this plugin routes to (UPPAAL / TLA+ / PRISM / SPIN).
- * v1 translates the core machine; unrepresentable invariants become warnings.
- */
-export const modelExportTool = defineTool({
-  name: EXPORT_TOOL_NAME,
-  description:
-    'Translate a LogicModelV1 into the input language of an external checker - UPPAAL, TLA+, PRISM or SPIN - for a property this plugin does not decide itself (symbolic model checking, unbounded induction, expected reward). format is one of uppaal (.xta + queries), tla (TLC spec + safety property), prism (.pm + .pctl), spin (Promela + ltl). This tool does not verify anything: for the checks it can decide use `model_verify`. Booleans are exported as 0/1 integers; invariants the target cannot express are returned as warnings, never silently dropped. Returns { ok, format, primary, extras?, warnings? } or { ok: false, error } when the model is invalid or the PRISM enumeration is too large.',
-  parameters: {
-    model: {
-      type: 'json',
-      required: true,
-      description: 'LogicModelV1 state-machine model to export.',
-    },
-    format: {
-      type: 'string',
-      required: true,
-      enum: ['uppaal', 'tla', 'prism', 'spin'],
-      description: 'Target tool format.',
-    },
-    reportView: {
-      type: 'string',
-      enum: ['digest', 'full'],
-      description: 'digest (default) prints the generated file verbatim; full prints the structured result as JSON.',
-    },
-  },
-  output: {
-    schema: {
-      type: 'json',
-      description: 'Export result with generated file content.',
-    },
-    render(args, value) {
-      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
-    },
-  },
-  timeoutMs: 10_000,
-  isConcurrencySafe: () => true,
-  async execute(args) {
-    try {
-      const result = exportModel(args.model, args.format as ExportFormat)
-      const warnings = result.warnings ?? []
-      const nextSteps: string[] = []
-      if (warnings.length > 0) nextSteps.push('The target notation cannot express some invariants; the warnings name each one — verify them in the target tool rather than assuming they carried over.')
-      nextSteps.push('Run the exported file through its own tool (verify/compile) before trusting the translation; this plugin guarantees the encoding, not the target checker\'s verdict.')
-      return {
-        ok: true,
-        ran: true,
-        ...verdictOf(0, warnings.length),
-        schema: REPORT_SCHEMAS.export,
-        format: result.format,
-        primary: result.primary,
-        ...(result.extras === undefined ? {} : { extras: result.extras }),
-        hashes: exportHashes(args.model),
-        warnings,
-        nextSteps,
-      } as unknown as JsonValue
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      // The exporter's own refusals carry their code: a limit of the encoding is not a defect in the model.
-      const errorCode = error instanceof ExportError ? error.code : 'MODEL_INVALID'
-      return { ok: false, ran: false, ...refusalVerdict(message), schema: REPORT_SCHEMAS.export, errorCode, error: message } as unknown as JsonValue
-    }
-  },
-})
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
+import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, validateModel, verdictOf } from './engine.js'
+import { cardWithSource, reportCallView, reportCard, reportResultView } from './presentation.js'
+import { ExportError, exportModel, type ExportFormat } from './exporters.js'
+import { renderReportText } from './report-view.js'
+
+/** The model hash of an export's input, when the input validates (the success path always does). */
+function exportHashes(model: unknown): { hashSpec: typeof DEFAULT_HASH_SPEC; modelHash?: string } {
+  const validation = validateModel(model)
+  return validation.ok
+    ? { hashSpec: DEFAULT_HASH_SPEC, modelHash: modelHash(validation.model) }
+    : { hashSpec: DEFAULT_HASH_SPEC }
+}
+
+export const EXPORT_TOOL_NAME = 'model_export'
+
+/**
+ * DSH tool wrapping the external-tool exporters: turn a LogicModelV1 machine into
+ * native input for the tool this plugin routes to (UPPAAL / TLA+ / PRISM / SPIN).
+ * v1 translates the core machine; unrepresentable invariants become warnings.
+ */
+export const modelExportTool = defineTool({
+  name: EXPORT_TOOL_NAME,
+  description:
+    'Translate a LogicModelV1 into the input language of an external checker - UPPAAL, TLA+, PRISM or SPIN - for a property this plugin does not decide itself (symbolic model checking, unbounded induction, expected reward). format is one of uppaal (.xta + queries), tla (TLC spec + safety property), prism (.pm + .pctl), spin (Promela + ltl). This tool does not verify anything: for the checks it can decide use `model_verify`. Booleans are exported as 0/1 integers; invariants the target cannot express are returned as warnings, never silently dropped. Returns { ok, format, primary, extras?, warnings? } or { ok: false, error } when the model is invalid or the PRISM enumeration is too large.',
+  parameters: {
+    model: {
+      type: 'json',
+      required: true,
+      description: 'LogicModelV1 state-machine model to export.',
+    },
+    format: {
+      type: 'string',
+      required: true,
+      enum: ['uppaal', 'tla', 'prism', 'spin'],
+      description: 'Target tool format.',
+    },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the generated file verbatim; full prints the structured result as JSON.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'Export result with generated file content.',
+    },
+    render(args, value) {
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
+    },
+    // The card a UI shows, separated from the text the model reads.
+    presentationMeta(_args, value) {
+      const report = value as Record<string, unknown>
+      return cardWithSource(value, EXPORT_TOOL_NAME, typeof report.primary === 'string' ? report.primary : undefined, typeof report.format === 'string' ? 'artifact: ' + report.format : 'artifact') as unknown as JsonValue
+    },
+  },
+  presentCall: reportCallView(EXPORT_TOOL_NAME),
+  presentResult: reportResultView(EXPORT_TOOL_NAME),
+
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    try {
+      const result = exportModel(args.model, args.format as ExportFormat)
+      const warnings = result.warnings ?? []
+      const nextSteps: string[] = []
+      if (warnings.length > 0) nextSteps.push('The target notation cannot express some invariants; the warnings name each one — verify them in the target tool rather than assuming they carried over.')
+      nextSteps.push('Run the exported file through its own tool (verify/compile) before trusting the translation; this plugin guarantees the encoding, not the target checker\'s verdict.')
+      return {
+        ok: true,
+        ran: true,
+        ...verdictOf(0, warnings.length),
+        schema: REPORT_SCHEMAS.export,
+        format: result.format,
+        primary: result.primary,
+        ...(result.extras === undefined ? {} : { extras: result.extras }),
+        hashes: exportHashes(args.model),
+        warnings,
+        nextSteps,
+      } as unknown as JsonValue
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      // The exporter's own refusals carry their code: a limit of the encoding is not a defect in the model.
+      const errorCode = error instanceof ExportError ? error.code : 'MODEL_INVALID'
+      return { ok: false, ran: false, ...refusalVerdict(message), schema: REPORT_SCHEMAS.export, errorCode, error: message } as unknown as JsonValue
+    }
+  },
+})

package/src/index.ts

@@ -39,6 +39,8 @@ import { umlRenderTool, umlParseTool, umlReviewTool, umlExplainLabelsTool } from
 import { umlStructureTool } from './structure-tool.js'
 import { designTool } from './design-tool.js'
 import { reportDiffTool } from './report-diff-tool.js'
+import { modelEditTool } from './edit-tool.js'
+import { modelAutomatonTool } from './automaton-tool.js'
 import { ENGINE_SCHEMA_VERSION } from './engine.js'
 
 // DSH 0.1.7-alpha.1 (session format v4) retires the shared
@@ -245,6 +247,8 @@ export function apply(ctx: Context, config: Config): void {
       ctx.effect(() => tools.register(umlStructureTool), 'dsh-model-everything: structure tool')
       ctx.effect(() => tools.register(designTool), 'dsh-model-everything: design review tool')
       ctx.effect(() => tools.register(reportDiffTool), 'dsh-model-everything: report diff tool')
+      ctx.effect(() => tools.register(modelEditTool), 'dsh-model-everything: model edit tool')
+      ctx.effect(() => tools.register(modelAutomatonTool), 'dsh-model-everything: automaton tool')
       toolRegistered = true
       dataToolRegistered = true
       concurrencyToolRegistered = true

package/src/presentation.ts

@@ -0,0 +1,365 @@
+/**
+ * What a UI shows for a report, separated from what the model reads.
+ *
+ * A report is written for a model: it names every check, every finding and the next step, because the
+ * model has to act on all of it. A reader wants four things instead - did it run, what does it decide,
+ * what is the first thing wrong, what to do next - and wants the rest folded away.
+ *
+ * Two host hooks carry that split:
+ *
+ * - `output.presentationMeta` projects a small JSON payload the host persists on the result; a client
+ *   card narrows it without parsing prose.
+ * - `presentResult` returns the card body from that payload, so a UI that supports it shows the summary
+ *   and a UI that does not falls back to the raw text. The model-facing content never changes.
+ *
+ * Both are pure and replayable: they read the persisted value, never the filesystem.
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { routeFor } from './routing.js'
+import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools'
+
+/** One finding, as a card needs it: a code to name it and a sentence to read. */
+export interface CardFinding {
+  code: string
+  severity: string
+  message: string
+}
+
+/** The payload a client card narrows. Small on purpose: a card is a summary, not a second report. */
+export interface ReportCard {
+  verdict?: string
+  verdictReason?: string
+  errors: number
+  warnings: number
+  checksRun?: number
+  first: CardFinding | null
+  /** The one step a reader should take, already a sentence. */
+  next: string | null
+  /** Which family produced this, so a card can pick an icon and a colour without parsing codes. */
+  family: string
+  /** What this family owns, and where the case just outside it goes. One table, not a second prose copy. */
+  route?: { owns: string; instead: string }
+  /** `model_edit`: the changes this call applied, as the report lists them. */
+  changes?: Array<{ kind: string; what: string; detail?: string }>
+  /** `model_edit` and `report_diff`: how the findings moved, when either report could compare. */
+  delta?: { added: number; removed: number; changed: number; addedErrors: number }
+  /** `report_diff`: the first finding the change adds, so a card can lead with it. */
+  firstAdded?: CardFinding
+  /** `report_diff`: the current report's own verdict, which differs from the delta's when a clean change lands on a failing report. */
+  currentVerdict?: string
+  /** The artifact a translation or a rendering produced, as the first lines of it. */
+  source?: { label: string; lines: string[]; total: number }
+  /** `uml_structure_verify`: the graph's own counts, which are measurements rather than findings. */
+  graph?: { nodes: number; edges: number; cycles: number; isolated: number; dangling: number }
+  /** `model_design_review`: three levels, because a signal is not a violation and a fact is neither. */
+  levels?: { violations: number; signals: number; facts: number; skipped: number }
+  /** `model_interleaving_scan`: how many claims were found, and in which families. */
+  claims?: { absolute: number; keywords: number; families: Array<{ family: string; count: number }> }
+}
+
+const SHORT = 160
+
+function shorten(text: string, limit = SHORT): string {
+  const flat = text.replace(/\s+/g, ' ').trim()
+  return flat.length <= limit ? flat : flat.slice(0, limit - 1).trimEnd() + '…'
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined
+}
+
+function array(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+/**
+ * Project a report into the card payload.
+ *
+ * Read defensively: this runs on replay too, and a payload that once had a shape may come back with a
+ * field missing. A card that throws would take the whole session view with it.
+ */
+export function reportCard(value: unknown, family: string): ReportCard {
+  const report = record(value) ?? {}
+  const findings = array(report.findings)
+    .map((entry) => record(entry))
+    .filter((entry): entry is Record<string, unknown> => entry !== undefined)
+  // Two shapes live under one payload: the families with a top-level `findings` array, and the verify
+  // family, whose findings sit inside `checks` and whose counts live in `summary`. Reading only the first
+  // shape made a failing verification card say "0 error(s)" while its own verdict said fail.
+  const violations = array(report.violations)
+  const signals = array(report.signals)
+  const facts = array(report.facts)
+  if (findings.length === 0 && violations.length > 0) {
+    // The design family keeps three levels apart on purpose: a violation decides the verdict, a signal is a
+    // structural fact, and a fact is a measurement. Only the violations are findings here, or the card would
+    // show a signal with an error mark.
+    for (const entry of violations) {
+      const finding = record(entry)
+      if (finding !== undefined) findings.push({ ...finding, severity: 'error' })
+    }
+  } else if (findings.length === 0 && violations.length === 0 && array(report.violations).length === 0 && !Array.isArray(report.violations)) {
+    for (const check of array(report.checks)) {
+      for (const entry of array(record(check)?.findings)) {
+        const finding = record(entry)
+        if (finding !== undefined) findings.push(finding)
+      }
+    }
+  }
+  const severity = (entry: Record<string, unknown>): string => String(entry.severity ?? 'info')
+  const errors = findings.filter((entry) => severity(entry) === 'error')
+  const warnings = findings.filter((entry) => severity(entry) === 'warning')
+  const summary = record(report.summary)
+  const summaryErrors = typeof summary?.errors === 'number' ? summary.errors : undefined
+  const summaryWarnings = typeof summary?.warnings === 'number' ? summary.warnings : undefined
+  const checksRun = typeof summary?.checksRun === 'number'
+    ? summary.checksRun
+    : array(report.checks).length > 0
+      ? array(report.checks).length
+      : undefined
+  const first = errors[0] ?? warnings[0]
+  const next = array(report.nextSteps).map((step) => String(step))[0]
+  const route = routeFor(family)
+  const deltaSummary = record(record(report.reportDelta)?.summary) ?? record(report.summary)
+  const delta = deltaSummary === undefined
+    ? undefined
+    : {
+        added: Number(deltaSummary.added ?? 0),
+        removed: Number(deltaSummary.removed ?? 0),
+        changed: Number(deltaSummary.changed ?? 0),
+        addedErrors: Number(deltaSummary.addedErrors ?? 0),
+      }
+  const changes = array(report.changes)
+    .map((entry) => record(entry))
+    .filter((entry): entry is Record<string, unknown> => entry !== undefined)
+    .map((entry) => ({ kind: String(entry.kind ?? '?'), what: String(entry.what ?? ''), ...(typeof entry.detail === 'string' && entry.detail !== '' ? { detail: entry.detail } : {}) }))
+  const firstAddedRaw = (array(report.added).map((entry) => record(entry)).find((entry) => entry !== undefined && String(entry.severity ?? '') === 'error')
+    ?? array(report.added).map((entry) => record(entry)).find((entry) => entry !== undefined))
+  return {
+    ...(typeof report.verdict === 'string' ? { verdict: report.verdict } : {}),
+    ...(typeof report.verdictReason === 'string' ? { verdictReason: shorten(report.verdictReason) } : {}),
+    errors: summaryErrors ?? errors.length,
+    warnings: summaryWarnings ?? warnings.length,
+    ...(checksRun === undefined ? {} : { checksRun }),
+    first: first === undefined
+      ? null
+      : { code: String(first.code ?? 'UNKNOWN'), severity: severity(first), message: shorten(String(first.message ?? '')) },
+    next: next === undefined ? null : shorten(next),
+    family,
+    ...(route === undefined ? {} : { route: { owns: route.owns, instead: route.notFor.tool } }),
+    ...(changes.length === 0 ? {} : { changes }),
+    ...(delta === undefined ? {} : { delta }),
+    ...(firstAddedRaw === undefined ? {} : { firstAdded: { code: String(firstAddedRaw.code ?? '?'), severity: String(firstAddedRaw.severity ?? 'info'), message: shorten(String(firstAddedRaw.message ?? '')) } }),
+    ...(typeof report.currentVerdict === 'string' ? { currentVerdict: report.currentVerdict } : {}),
+    ...(typeof summary?.nodes === 'number' && typeof summary?.edges === 'number'
+      ? { graph: { nodes: summary.nodes, edges: summary.edges, cycles: Number(summary.cycles ?? 0), isolated: Number(summary.isolated ?? 0), dangling: Number(summary.dangling ?? 0) } }
+      : {}),
+    ...(violations.length === 0 && signals.length === 0 && facts.length === 0
+      ? {}
+      : { levels: { violations: violations.length, signals: signals.length, facts: facts.length, skipped: array(report.checksSkipped).length } }),
+    ...(typeof summary?.absoluteClaims === 'number'
+      ? { claims: { absolute: summary.absoluteClaims, keywords: Number(summary.keywords ?? 0), families: claimFamilies(findings) } }
+      : {}),
+  }
+}
+
+/** The card body: four lines, in the order a reader asks the questions. */
+export function cardBlocks(card: ReportCard): ContentBlock[] {
+  const lines: string[] = []
+  const head = card.verdict === undefined ? card.family : card.verdict.toUpperCase()
+  const counts = card.checksRun === undefined
+    ? `${String(card.errors)} error(s), ${String(card.warnings)} warning(s)`
+    : `${String(card.checksRun)} checks · ${String(card.errors)} error(s) · ${String(card.warnings)} warning(s)`
+  lines.push(head + '  —  ' + counts)
+  if (card.verdictReason !== undefined) lines.push(card.verdictReason)
+  if (card.first != null) {
+    // A finding with no message prints its code and stops: a colon with nothing after it reads as a
+    // truncated message rather than as an absent one.
+    const mark = card.first.severity === 'error' ? '✗ ' : '⚠ '
+    lines.push(mark + card.first.code + (card.first.message.trim() === '' ? '' : ': ' + card.first.message))
+  }
+  if (card.next != null) lines.push('next: ' + card.next)
+  if (card.source !== undefined) {
+    lines.push('')
+    const shown = card.source.lines.length
+    lines.push(card.source.label + (card.source.total > shown ? ' (first ' + String(shown) + ' of ' + String(card.source.total) + ' lines)' : ''))
+    lines.push(...card.source.lines)
+  }
+  return [{ type: 'text', text: lines.join('\n') }]
+}
+
+/**
+ * `presentResult` for a report tool: render the card from the persisted payload, and fall back to the
+ * raw content by returning undefined when there is none.
+ */
+/** The last path segment, for a title. No `node:path` here: this runs on replay too. */
+function lastSegment(path: string): string {
+  const parts = path.split(/[\\/]/).filter((part) => part !== '' && part !== '.')
+  return parts[parts.length - 1] ?? path
+}
+
+/**
+ * The pending card for a report tool: a title naming the artifact, and the file to follow.
+ *
+ * From the arguments only, because a UI calls this during streaming and again on replay; the file has not
+ * been opened at that point and must not be.
+ */
+
+/**
+ * The card payload with the artifact previewed.
+ *
+ * A translation and a rendering both produce text a reader wants to see the shape of, and neither should
+ * paste the whole file into a card: the preview is bounded, and it says how much it left out. The report
+ * keeps the artifact in full for whoever needs it.
+ */
+export function cardWithSource(value: unknown, family: string, text: string | undefined, label: string, limit = 14): ReportCard {
+  const card = reportCard(value, family)
+  if (text === undefined || text.trim() === '') return card
+  const all = text.split(String.fromCharCode(10))
+  const lines = all.slice(0, limit)
+  return { ...card, source: { label, lines, total: all.length } }
+}
+
+export function reportCallView(family: string) {
+  return (args: unknown): ToolCallView | undefined => {
+    const a = record(args) ?? {}
+    const path = ['modelPath', 'repoPath', 'path']
+      .map((key) => a[key])
+      .find((value): value is string => typeof value === 'string' && value !== '')
+    const kind = family === 'model_edit' ? 'edit' : family.startsWith('uml_') ? 'search' : 'other'
+    const title = path === undefined ? family : family + '  ' + lastSegment(path)
+    return { card: 'generic', title, kind, ...(path === undefined ? {} : { locations: [{ path }] }) }
+  }
+}
+
+/**
+ * The card for `model_edit`: what changed, and what the change did to the findings.
+ *
+ * Both lists are already in the report, so this is a rendering of the same value rather than a second
+ * computation - the rule every card here follows.
+ */
+export function editCardBlocks(card: ReportCard): ContentBlock[] {
+  const changes = card.changes ?? []
+  const lines: string[] = []
+  const head = card.verdict === undefined ? card.family : card.verdict.toUpperCase()
+  lines.push(head + (changes.length === 0 ? '  —  no change was applied' : '  —  ' + String(changes.length) + ' change(s)'))
+  for (const change of changes.slice(0, 6)) {
+    lines.push('· ' + change.kind + ' ' + change.what + (change.detail === undefined ? '' : ' (' + change.detail + ')'))
+  }
+  if (changes.length > 6) lines.push('· … ' + String(changes.length - 6) + ' more in the report')
+  if (card.delta !== undefined) {
+    lines.push('findings: added ' + String(card.delta.added) + ' (' + String(card.delta.addedErrors) + ' error) · removed ' + String(card.delta.removed) + ' · changed ' + String(card.delta.changed))
+  }
+  if (card.next != null) lines.push('next: ' + card.next)
+  return [{ type: 'text', text: lines.join('\n') }]
+}
+
+/**
+ * The card for `report_diff`: does this change add anything, read as counts and the first added error.
+ *
+ * A diff's `verdict` is about the delta, so the card leads with the delta and never with the current
+ * report's own verdict - the two differ exactly when a clean change lands on an already-failing report.
+ */
+export function diffCardBlocks(card: ReportCard): ContentBlock[] {
+  const delta = card.delta
+  const lines: string[] = []
+  const head = card.verdict === undefined ? card.family : card.verdict.toUpperCase()
+  lines.push(head + '  —  added ' + String(delta?.added ?? 0) + ' (' + String(delta?.addedErrors ?? 0) + ' error) · removed ' + String(delta?.removed ?? 0) + ' · changed ' + String(delta?.changed ?? 0))
+  if (card.currentVerdict !== undefined) lines.push('the current report on its own: ' + card.currentVerdict)
+  if (card.firstAdded !== undefined) lines.push('✗ ' + card.firstAdded.code + ': ' + card.firstAdded.message)
+  if ((delta?.added ?? 0) === 0) lines.push('nothing was added: this change is accepted by the "no new findings" rule')
+  if (card.next != null) lines.push('next: ' + card.next)
+  return [{ type: 'text', text: lines.join('\n') }]
+}
+
+/** `presentResult` for `model_edit`, falling back to the generic card when the payload has no changes. */
+export function editResultView(family: string) {
+  return (_args: unknown, result: { content: ContentBlock[]; meta?: unknown }): ToolResultView | undefined => {
+    const card = record(result.meta) as unknown as ReportCard | undefined
+    if (card === undefined || card === null) return undefined
+    const changeCount = card.changes === undefined ? '' : '  ·  ' + String(card.changes.length) + ' change(s)'
+    return { card: 'generic', title: family + '  ' + (card.verdict ?? '') + changeCount, content: editCardBlocks(card) }
+  }
+}
+
+export function reportResultView(family: string) {
+  return (_args: unknown, result: { content: ContentBlock[]; meta?: unknown }): ToolResultView | undefined => {
+    const card = record(result.meta) as unknown as ReportCard | undefined
+    if (card === undefined || card === null) return undefined
+    if (card.verdict === undefined && card.next == null && card.first == null) return undefined
+    return { card: 'generic', title: family + '  ' + (card.verdict ?? '') , content: cardBlocks(card) }
+  }
+}
+
+
+/** How many findings per family, for the scan card: the reader wants the shape, not the list. */
+function claimFamilies(findings: Array<Record<string, unknown>>): Array<{ family: string; count: number }> {
+  const counts = new Map<string, number>()
+  for (const finding of findings) {
+    const family = typeof finding.family === 'string' ? finding.family : 'other'
+    counts.set(family, (counts.get(family) ?? 0) + 1)
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([family, count]) => ({ family, count }))
+}
+
+/** The card for `uml_structure_verify`: the graph's shape first, then the first finding. */
+export function structureCardBlocks(card: ReportCard): ContentBlock[] {
+  const lines: string[] = []
+  const head = card.verdict === undefined ? card.family : card.verdict.toUpperCase()
+  lines.push(head + '  —  ' + String(card.errors) + ' error(s) · ' + String(card.warnings) + ' warning(s)')
+  if (card.graph !== undefined) {
+    lines.push('graph: ' + String(card.graph.nodes) + ' nodes · ' + String(card.graph.edges) + ' edges · ' + String(card.graph.cycles) + ' cycle(s) · ' + String(card.graph.isolated) + ' isolated')
+  }
+  if (card.first != null) lines.push((card.first.severity === 'error' ? '✗ ' : '⚠ ') + card.first.code + ': ' + card.first.message)
+  if (card.next != null) lines.push('next: ' + card.next)
+  return [{ type: 'text', text: lines.join(String.fromCharCode(10)) }]
+}
+
+/** The card for `model_design_review`: violations, then signals, then facts - never one number. */
+export function designCardBlocks(card: ReportCard): ContentBlock[] {
+  const lines: string[] = []
+  const head = card.verdict === undefined ? card.family : card.verdict.toUpperCase()
+  lines.push(head + '  —  ' + String(card.errors) + ' violation(s) · ' + String(card.warnings) + ' signal(s)')
+  if (card.levels !== undefined) {
+    lines.push('levels: ' + String(card.levels.violations) + ' violation · ' + String(card.levels.signals) + ' signal · ' + String(card.levels.facts) + ' fact · ' + String(card.levels.skipped) + ' check(s) skipped')
+  }
+  if (card.first != null) lines.push('✗ ' + card.first.code + ': ' + card.first.message)
+  if (card.levels !== undefined && card.levels.skipped > 0) lines.push('a skipped check examined nothing: silence there is not a pass')
+  if (card.next != null) lines.push('next: ' + card.next)
+  return [{ type: 'text', text: lines.join(String.fromCharCode(10)) }]
+}
+
+/** The card for `model_interleaving_scan`: claims by family, and the reminder that nothing was proven. */
+export function scanCardBlocks(card: ReportCard): ContentBlock[] {
+  const lines: string[] = []
+  const head = card.verdict === undefined ? card.family : card.verdict.toUpperCase()
+  lines.push(head + '  —  ' + String(card.errors) + ' absolute claim(s) · ' + String(card.warnings) + ' risk(s)')
+  if (card.claims !== undefined) {
+    const families = card.claims.families.map((entry) => entry.family + ' ' + String(entry.count)).join(' · ')
+    lines.push('claims: ' + String(card.claims.absolute) + ' absolute, ' + String(card.claims.keywords) + ' keyword(s) hit' + (families === '' ? '' : ' · ' + families))
+  }
+  if (card.first != null) lines.push('✗ ' + card.first.code + ': ' + card.first.message)
+  lines.push('this plugin routed the claims; it proved none of them')
+  return [{ type: 'text', text: lines.join(String.fromCharCode(10)) }]
+}
+
+/** One `presentResult` per card body, since the shapes differ but the fallback does not. */
+export function familyResultView(family: string, body: (card: ReportCard) => ContentBlock[]) {
+  return (_args: unknown, result: { content: ContentBlock[]; meta?: unknown }): ToolResultView | undefined => {
+    const card = record(result.meta) as unknown as ReportCard | undefined
+    if (card === undefined || card === null) return undefined
+    return { card: 'generic', title: family + '  ' + (card.verdict ?? ''), content: body(card) }
+  }
+}
+
+export const structureResultView = familyResultView('uml_structure_verify', structureCardBlocks)
+export const designResultView = familyResultView('model_design_review', designCardBlocks)
+export const scanResultView = familyResultView('model_interleaving_scan', scanCardBlocks)
+
+/** `presentResult` for `report_diff`: the delta leads, never the current report's own verdict. */
+export function diffResultView(family: string) {
+  return (_args: unknown, result: { content: ContentBlock[]; meta?: unknown }): ToolResultView | undefined => {
+    const card = record(result.meta) as unknown as ReportCard | undefined
+    if (card === undefined || card === null) return undefined
+    return { card: 'generic', title: family + '  ' + (card.verdict ?? ''), content: diffCardBlocks(card) }
+  }
+}

package/src/report-diff-tool.ts

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { diffReports } from './baseline.js'
 import { refusalVerdict } from './engine.js'
+import { diffResultView, reportCallView, reportCard } from './presentation.js'
 import { renderReportText } from './report-view.js'
 
 export const REPORT_DIFF_TOOL_NAME = 'report_diff'
@@ -54,7 +55,14 @@ export const reportDiffTool = defineTool({
     render(args, value) {
       return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
     },
+    // The card a UI shows, separated from the text the model reads.
+    presentationMeta(_args, value) {
+      return reportCard(value, REPORT_DIFF_TOOL_NAME) as unknown as JsonValue
+    },
   },
+  presentCall: reportCallView(REPORT_DIFF_TOOL_NAME),
+  presentResult: diffResultView(REPORT_DIFF_TOOL_NAME),
+
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {