dsh-model-everything 0.1.0 → 0.3.0

package/src/model-file.ts

@@ -0,0 +1,49 @@
+/**
+ * Read a JSON model from a file instead of requiring it inline.
+ *
+ * A model is the largest argument any of these tools takes, and it is the one that arrives as
+ * streamed tool-call JSON: the provider rejected one session with `tool input is invalid JSON`
+ * after the model spent sixteen steps hand-editing a nested model argument. Reading it from the
+ * workspace removes that failure mode and the tokens.
+ */
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { OptionShapeError } from './option-shape.js'
+
+/** Read and parse one JSON file. Formatting is irrelevant: whitespace, BOM and pretty printing all parse. */
+export function readJsonFile(path: unknown, option: string, code: string): unknown {
+  if (typeof path !== 'string' || path.trim() === '') {
+    throw new OptionShapeError(code, `${option} must be a non-empty path to a JSON file.`)
+  }
+  const full = resolve(path)
+  let text: string
+  try {
+    text = readFileSync(full, 'utf8')
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new OptionShapeError(code, `${option} could not be read: ${reason}. The path resolves against the process working directory; relative paths in a session resolve against the session's workspace.`)
+  }
+  try {
+    return JSON.parse(text.replace(/^\uFEFF/, ''))
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new OptionShapeError(code, `${option} is not valid JSON: ${reason}.`)
+  }
+}
+
+/**
+ * Exactly one of the inline value and the file path. Both is ambiguous, neither is a missing
+ * argument, and each gets its own sentence so the caller knows which one to drop.
+ */
+export function oneOf(value: unknown, path: unknown, inlineName: string, pathName: string, code: string): unknown {
+  const hasValue = value !== undefined
+  const hasPath = path !== undefined
+  if (hasValue && hasPath) {
+    throw new OptionShapeError(code, `Pass either ${inlineName} or ${pathName}, not both: the file would be read and then ignored, or the other way round.`)
+  }
+  if (!hasValue && !hasPath) {
+    throw new OptionShapeError(code, `Pass ${inlineName} or ${pathName}: the model has to come from somewhere.`)
+  }
+  return hasPath ? readJsonFile(path, pathName, code) : value
+}

package/src/presentation.ts

@@ -0,0 +1,125 @@
+/**
+ * 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 { 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 }
+}
+
+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)
+  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 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]
+  return {
+    ...(typeof report.verdict === 'string' ? { verdict: report.verdict } : {}),
+    ...(typeof report.verdictReason === 'string' ? { verdictReason: shorten(report.verdictReason) } : {}),
+    errors: errors.length,
+    warnings: 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,
+    ...(routeFor(family) === undefined
+      ? {}
+      : { route: { owns: routeFor(family)?.owns ?? '', instead: routeFor(family)?.notFor.tool ?? '' } }),
+  }
+}
+
+/** 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) {
+    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('\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.
+ */
+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) }
+  }
+}

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 { reportCard, reportResultView } from './presentation.js'
 import { renderReportText } from './report-view.js'
 
 export const REPORT_DIFF_TOOL_NAME = 'report_diff'
@@ -54,7 +55,12 @@ 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
+    },
+  },  presentResult: reportResultView(REPORT_DIFF_TOOL_NAME),
+
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {