@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/mcp/mcp-traces.ts

@@ -0,0 +1,409 @@
+import type { toTrace } from '../local/local-traces'
+import { studioLink, type RuntimeLink } from './mcp-runtime'
+
+/**
+ * Traces for the coding agent, read from the runtime's local trace store
+ * (the Langfuse-compatible API Studio's trace views use) and cut down to
+ * what an agent reasons about: the span tree, tool calls, tokens, errors.
+ */
+
+type LocalTrace = ReturnType<typeof toTrace>
+type Observation = LocalTrace['observations'][number]
+
+export interface TraceSummary {
+  id: string
+  name: string
+  at: string
+  conversationId: string | null
+  level: string
+  seconds: number
+  tokens: number
+  link: string
+}
+
+export interface TraceNode {
+  name: string
+  type: string
+  ms: number | null
+  model?: string
+  tokens?: { input: number; output: number; total: number }
+  error?: string
+  input?: string
+  output?: string
+  /** A \`reply.blocked\` span: which check fired and its outcome; the trace's \`replyChecks\` has the findings and both drafts. */
+  replyCheck?: string
+  children?: TraceNode[]
+}
+
+const CLIP = 1_500
+
+function clip(value: unknown): string | undefined {
+  if (value === null || value === undefined) return undefined
+  const text = typeof value === 'string' ? value : JSON.stringify(value)
+  return text.length > CLIP ? `${text.slice(0, CLIP)}… (${text.length - CLIP} more characters)` : text
+}
+
+/** Studio's page for one trace. */
+export function traceLink(link: RuntimeLink, id: string): string {
+  return studioLink(link, `/traces?trace=${encodeURIComponent(id)}`)
+}
+
+async function tracesCall<T>(link: RuntimeLink, path: string): Promise<T | null> {
+  const res = await fetch(new URL(path, link.tracesUrl), { signal: AbortSignal.timeout(15_000) })
+  if (res.status === 404) return null
+  if (!res.ok) throw new Error(`local traces answered ${res.status}`)
+  return (await res.json()) as T
+}
+
+function tokensOf(trace: LocalTrace): number {
+  return trace.observations.reduce((n, o) => n + (o.usage?.total ?? 0), 0)
+}
+
+export function summarize(link: RuntimeLink, trace: LocalTrace): TraceSummary {
+  return {
+    id: trace.id,
+    name: trace.name,
+    at: trace.timestamp,
+    conversationId: trace.sessionId,
+    level: trace.level,
+    seconds: Math.round(trace.latency * 100) / 100,
+    tokens: tokensOf(trace),
+    link: traceLink(link, trace.id),
+  }
+}
+
+/** Recent traces, newest first, narrowed in this process: the store filters only by time, metadata and level. */
+export async function listTraces(link: RuntimeLink, opts: { limit: number; conversationId?: string; errorsOnly?: boolean; name?: string; since?: string }): Promise<TraceSummary[]> {
+  const filter = opts.since ? [{ type: 'datetime', column: 'timestamp', operator: '>=', value: opts.since }] : []
+  const page = await tracesCall<{ data: LocalTrace[] }>(link, `/api/public/traces?limit=100&filter=${encodeURIComponent(JSON.stringify(filter))}`)
+  const traces = (page?.data ?? []).filter(
+    (t) =>
+      (!opts.conversationId || t.sessionId === opts.conversationId) &&
+      (!opts.errorsOnly || t.level === 'ERROR') &&
+      (!opts.name || t.name.toLowerCase().includes(opts.name.toLowerCase())),
+  )
+  return traces.slice(0, opts.limit).map((t) => summarize(link, t))
+}
+
+export async function getTrace(link: RuntimeLink, id: string): Promise<LocalTrace | null> {
+  return tracesCall<LocalTrace>(link, `/api/public/traces/${encodeURIComponent(id)}`)
+}
+
+function node(o: Observation, children: Map<string, Observation[]>, detail: boolean): TraceNode {
+  const kids = (children.get(o.id) ?? []).map((c) => node(c, children, detail))
+  return {
+    name: o.name,
+    type: o.type.toLowerCase(),
+    ms: o.latency === null ? null : Math.round(o.latency * 1000),
+    ...(o.model ? { model: o.model } : {}),
+    ...(o.usage ? { tokens: { input: o.usage.input, output: o.usage.output, total: o.usage.total } } : {}),
+    ...(o.level === 'ERROR' ? { error: o.statusMessage ?? 'failed' } : {}),
+    ...(detail ? { input: clip(o.input), output: clip(o.output) } : {}),
+    ...(isReplyBlocked(o.name) ? { replyCheck: `${String(o.metadata?.guardrail ?? o.metadata?.check ?? 'a check')} fired, outcome ${String(o.metadata?.outcome ?? 'unknown')}: replyChecks has what it found and both drafts` } : {}),
+    ...(kids.length ? { children: kids } : {}),
+  }
+}
+
+/** A trace as the agent reads it: the tree, the tool calls in order, totals and every error. */
+export function readTrace(link: RuntimeLink, trace: LocalTrace, opts: { detail: boolean }) {
+  const ids = new Set(trace.observations.map((o) => o.id))
+  const children = new Map<string, Observation[]>()
+  const roots: Observation[] = []
+  for (const o of trace.observations) {
+    if (o.parentObservationId && ids.has(o.parentObservationId)) {
+      const list = children.get(o.parentObservationId) ?? []
+      list.push(o)
+      children.set(o.parentObservationId, list)
+    } else roots.push(o)
+  }
+  const tools = trace.observations
+    .filter((o) => o.type === 'TOOL' || /^(ai\.toolCall|tool[:.\s])/i.test(o.name))
+    .map((o) => ({ name: o.name.replace(/^(ai\.toolCall|tool)[:.\s]*/i, '') || o.name, ms: o.latency === null ? null : Math.round(o.latency * 1000), ok: o.level !== 'ERROR', input: clip(o.input), output: clip(o.output) }))
+  const errors = trace.observations.filter((o) => o.level === 'ERROR').map((o) => ({ span: o.name, message: o.statusMessage ?? 'failed' }))
+  const procedures = proceduresOf(trace.observations)
+  const replyChecks = replyChecksOfTrace(trace.observations)
+  const toolsOffered = toolsOfferedOf(trace.observations)
+  const dataScopes = dataScopesOf(trace.observations)
+  const version = agentVersionOf(trace)
+  return {
+    ...summarize(link, trace),
+    ...version,
+    ...(procedures ? { procedures } : {}),
+    // The tools each model call was offered (`pi.turn <n>`): what the Agent could have called, beside what it did.
+    ...(toolsOffered.length ? { toolsOffered } : {}),
+    // Each data scope the turn's Blueprint reads were narrowed by: the type, property, variable and whether it had a value.
+    ...(dataScopes.length ? { dataScopes } : {}),
+    // Each time the reply check changed a reply: the check, what it found, what the person got, both drafts.
+    ...(replyChecks.length ? { replyChecks } : {}),
+    totals: {
+      spans: trace.observations.length,
+      generations: trace.observations.filter((o) => o.type === 'GENERATION').length,
+      toolCalls: tools.length,
+      tokens: tokensOf(trace),
+      cost: trace.totalCost || undefined,
+    },
+    input: clip(trace.input),
+    output: clip(trace.output),
+    errors,
+    toolCalls: tools,
+    tree: roots.map((r) => node(r, children, opts.detail)),
+  }
+}
+
+/**
+ * The tool set each model call of the turn was offered, from the generations
+ * named `pi.turn <n>` (`metadata.toolsOffered`, `toolCount`). A call offered
+ * the same set as the one before it is folded into it (`turns`). A compact
+ * run lists `activate_capability` for what it has not loaded yet.
+ */
+export function toolsOfferedOf(observations: Observation[]): Array<{ turns: string[]; count: number; tools: string[]; note?: string }> {
+  const out: Array<{ turns: string[]; count: number; tools: string[]; note?: string }> = []
+  const ordered = [...observations].filter((o) => /^pi\.turn\b/.test(o.name)).sort((a, b) => Date.parse(String(a.startTime ?? '')) - Date.parse(String(b.startTime ?? '')))
+  for (const o of ordered) {
+    const offered = o.metadata?.toolsOffered
+    if (!Array.isArray(offered)) continue
+    const tools = offered.filter((t): t is string => typeof t === 'string')
+    const count = typeof o.metadata?.toolCount === 'number' ? o.metadata.toolCount : tools.length
+    const last = out[out.length - 1]
+    if (last && last.tools.join('\n') === tools.join('\n')) {
+      last.turns.push(o.name)
+      continue
+    }
+    out.push({ turns: [o.name], count, tools, ...(tools.includes('activate_capability') ? { note: 'activate_capability stands for capabilities not loaded yet: the Agent loads one by calling it, and the next call is offered its tools' } : {}) })
+  }
+  return out
+}
+
+/** The data scopes a turn's Blueprint reads ran under (`blueprint.data-scope` spans, `metadata.scopes`). */
+export function dataScopesOf(observations: Observation[]): Array<Record<string, unknown>> {
+  return observations
+    .filter((o) => o.name === 'blueprint.data-scope')
+    .flatMap((o) => (Array.isArray(o.metadata?.scopes) ? (o.metadata.scopes as unknown[]) : []))
+    .filter((x): x is Record<string, unknown> => !!x && typeof x === 'object' && !Array.isArray(x))
+}
+
+/** Which version of the Agent ran: the draft (and whose draft) when the trace says so, as a Function's `ctx.agent()` on the local runtime does. */
+function agentVersionOf(trace: LocalTrace): { agentVersion?: string; draftOf?: string } {
+  const meta = (trace as { metadata?: Record<string, unknown> }).metadata ?? {}
+  const version = typeof meta.agentVersion === 'string' ? meta.agentVersion : undefined
+  const draftOf = typeof meta.draftOf === 'string' ? meta.draftOf : undefined
+  return { ...(version ? { agentVersion: version } : {}), ...(draftOf ? { draftOf } : {}) }
+}
+
+/** A conversation's traces, newest first, whole: what a turn's trace is chosen from. */
+export async function conversationTraces(link: RuntimeLink, conversationId: string, since?: string): Promise<LocalTrace[]> {
+  const filter = since ? [{ type: 'datetime', column: 'timestamp', operator: '>=', value: since }] : []
+  const page = await tracesCall<{ data: LocalTrace[] }>(link, `/api/public/traces?limit=100&filter=${encodeURIComponent(JSON.stringify(filter))}`)
+  return (page?.data ?? []).filter((t) => t.sessionId === conversationId)
+}
+
+/** The trace's root span (no parent at all) has ended: every span under it ended before it, so the trace is whole. */
+export function traceComplete(trace: LocalTrace): boolean {
+  return trace.observations.some((o) => !o.parentObservationId && o.endTime !== null)
+}
+
+const hasUsage = (trace: LocalTrace) => trace.observations.some((o) => o.type === 'GENERATION' && o.usage !== null)
+const hasGeneration = (trace: LocalTrace) => trace.observations.some((o) => o.type === 'GENERATION')
+
+/**
+ * The trace of ONE turn: among the conversation's traces that were not there
+ * before the turn was sent, the earliest that called a model (a title or a
+ * summary the runtime writes afterwards is a trace of its own, and later).
+ */
+export function pickTurnTrace(traces: LocalTrace[], before: ReadonlySet<string>): LocalTrace | null {
+  const fresh = traces.filter((t) => !before.has(t.id)).sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))
+  return fresh.find(hasGeneration) ?? fresh[0] ?? null
+}
+
+export interface TurnTrace {
+  summary: TraceSummary
+  /** The models the turn's generations ran on, as the provider named them. */
+  models: string[]
+  /** Not every span had arrived, or no model call reported usage: `tokens` is a floor, not the total. */
+  tokensPartial: boolean
+  trace: LocalTrace
+}
+
+/**
+ * The trace a turn produced. Spans are exported in batches, so a trace
+ * shows up in pieces a few seconds after the reply: wait until its root span
+ * has ended (the whole turn is in) for at most `waitMs`, then sum what is
+ * there and say whether that is all of it.
+ */
+export async function awaitTurnTrace(
+  link: RuntimeLink,
+  conversationId: string,
+  opts: { before: ReadonlySet<string>; since: string; waitMs?: number; pollMs?: number },
+): Promise<TurnTrace | null> {
+  const deadline = Date.now() + (opts.waitMs ?? 20_000)
+  let last: LocalTrace | null = null
+  for (;;) {
+    const traces = await conversationTraces(link, conversationId, opts.since).catch(() => [] as LocalTrace[])
+    last = pickTurnTrace(traces, opts.before) ?? last
+    // Children end before their root, so a trace whose root has ended is whole.
+    if ((last && traceComplete(last)) || Date.now() > deadline) break
+    await new Promise((r) => setTimeout(r, opts.pollMs ?? 750))
+  }
+  if (!last) return null
+  const models = [...new Set(last.observations.filter((o) => o.type === 'GENERATION' && o.model).map((o) => o.model!))]
+  return { summary: summarize(link, last), models, tokensPartial: !traceComplete(last) || !hasUsage(last), trace: last }
+}
+
+const PROCEDURE_REASONS: Record<string, string> = {
+  start: "it is the conversation's start procedure",
+  keyword: 'a message contained one of its keywords',
+  active: 'it was already active from an earlier turn',
+  none: 'no procedure applies to this turn',
+}
+
+export interface ProcedureTurn {
+  id: string | null
+  name: string | null
+  reason: string
+  why: string
+  keywords?: unknown
+  alsoTriggered?: unknown
+  tools?: unknown
+  handover?: unknown
+  handsOver?: unknown
+}
+
+/**
+ * Which procedure each model turn ran under and why (`procedure.active`
+ * spans, one per pi turn of an Agent with procedures), and the procedures
+ * the model loaded through `skill` (`procedure.loaded`). Null when the trace
+ * has neither: an Agent without procedures, or a runtime that does not
+ * record them.
+ */
+export function proceduresOf(observations: Array<{ name: string; startTime?: string | null; metadata?: Record<string, unknown> | null }>): { active: ProcedureTurn | null; turns?: ProcedureTurn[]; loaded?: Array<Record<string, unknown>> } | null {
+  const ordered = [...observations].sort((a, b) => Date.parse(a.startTime ?? '') - Date.parse(b.startTime ?? ''))
+  const turns = ordered
+    .filter((o) => o.name === 'procedure.active')
+    .map((o): ProcedureTurn => {
+      const m = o.metadata ?? {}
+      const reason = typeof m.reason === 'string' ? m.reason : 'unknown'
+      const has = (v: unknown) => v !== undefined && v !== null && !(Array.isArray(v) && v.length === 0)
+      return {
+        id: typeof m.procedureId === 'string' ? m.procedureId : null,
+        name: typeof m.procedureName === 'string' ? m.procedureName : null,
+        reason,
+        why: PROCEDURE_REASONS[reason] ?? 'the runtime gave no reason it knows',
+        ...(has(m.keywords) ? { keywords: m.keywords } : {}),
+        ...(has(m.alsoTriggered) ? { alsoTriggered: m.alsoTriggered } : {}),
+        ...(has(m.tools) ? { tools: m.tools } : {}),
+        ...(has(m.handover) ? { handover: m.handover } : {}),
+        ...(has(m.procedureHandsOver) ? { handsOver: m.procedureHandsOver } : {}),
+      }
+    })
+  const loaded = ordered.filter((o) => o.name === 'procedure.loaded').map((o) => ({ ...(o.metadata ?? {}) }))
+  if (!turns.length && !loaded.length) return null
+  const differ = new Set(turns.map((t) => `${t.id}:${t.reason}`)).size > 1
+  return { active: turns.at(-1) ?? null, ...(differ ? { turns } : {}), ...(loaded.length ? { loaded } : {}) }
+}
+
+/* ------------------------------------------------------------------ *
+ * The reply check
+ * ------------------------------------------------------------------ */
+
+/** What a claim kind means: the sentence the reply was read as saying. */
+const CLAIM_KINDS: Record<string, string> = {
+  action: 'that an action was, is being or will be carried out',
+  escalation: 'that the request was passed on to someone, or that a person or team will take it up',
+  channel: 'a way to reach someone (a contact, a page, a desk or a sign-in route; the finding names the phrases) that nothing the Agent was given mentions',
+}
+
+/** What the person read instead of the first draft, by the check's outcome. */
+const OUTCOMES: Record<string, { got: string; fixedReply: boolean }> = {
+  regenerated: { got: 'the second draft: the Agent rewrote the reply after the correction, and the rewrite passed', fixedReply: false },
+  template: { got: "the fixed safe reply (\"Sorry, I can't answer that right now…\" or its translation): the rewrite failed the check too, so neither draft was sent", fixedReply: true },
+  deferred: { got: 'the reply the Agent wrote after the tools it called beside this text had run (checked again then); this text was held back', fixedReply: false },
+  'sends-dropped': { got: 'neither draft: the rewrite failed too, so its messages were dropped, and the tools called beside them still ran', fixedReply: false },
+}
+
+const DRAFT_CLIP = 800
+
+function clipDraft(value: unknown): string | undefined {
+  if (typeof value !== 'string' || !value) return undefined
+  return value.length > DRAFT_CLIP ? `${value.slice(0, DRAFT_CLIP)}… (${value.length - DRAFT_CLIP} more characters)` : value
+}
+
+const RESERVED = new Set(['guardrail', 'check', 'outcome', 'harness', 'correction', 'firstDraft', 'secondDraft', 'drafts', 'draft', 'secondGuardrail', 'secondDetail', 'secondCheck', 'reason'])
+
+/** What one check found, in words, from its name and findings. */
+function foundBy(check: string, findings: Record<string, unknown>, reason: unknown): string {
+  const list = (v: unknown) => (Array.isArray(v) ? v.map(String) : typeof v === 'string' ? [v] : [])
+  if (check === 'claims') {
+    const kinds = list(findings.kinds)
+    const read = kinds.map((k) => `${k}: it says ${CLAIM_KINDS[k] ?? 'something the check does not name'}`)
+    return `The reply claims something no tool did in this conversation${read.length ? ` (${read.join('; ')})` : ''}.`
+  }
+  // The figures check is gone; older sessions' traces still carry it.
+  if (check === 'figures') return `The reply states ${list(findings.figures).join(', ') || 'figures'}, which nothing the Agent was given (instructions, messages, tool results, its own call arguments) contains.`
+  if (check === 'output') return `The reply uses "${String(findings.term ?? '?')}", a term this Agent must not say.`
+  if (check === 'length') return `A message the Agent was sending is ${String(findings.characters ?? '?')} characters, over the Agent's limit.`
+  if (check === 'empty') return typeof findings.reason === 'string' ? findings.reason : 'The model wrote no reply text.'
+  return typeof reason === 'string' && reason ? reason : `The ${check} check failed.`
+}
+
+export interface ReplyCheck {
+  /** The check that failed: claims, output (a blocked term), length, empty; figures in older traces. */
+  check: string
+  found: string
+  findings: Record<string, unknown>
+  outcome: string
+  /** What the person read, in words. */
+  personGot: string
+  /** The person read the fixed safe reply, not anything the Agent wrote. */
+  replacedWithFixedReply: boolean
+  correction?: string
+  firstDraft?: string
+  secondDraft?: string
+  /** The rewrite failed a check too: which, and what it found. */
+  secondCheck?: { check: string; found: string; findings: Record<string, unknown> }
+  at?: string
+}
+
+/**
+ * A `reply.blocked` record — the session event's payload or the span's
+ * metadata, which carry the same fields — read defensively: the check, what
+ * it found, what the person got instead, and both drafts, clipped.
+ */
+export function replyCheckOf(raw: Record<string, unknown> | null | undefined, at?: string | null): ReplyCheck {
+  const r = raw ?? {}
+  const check = String(r.guardrail ?? r.check ?? 'unknown')
+  const findings: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(r)) if (!RESERVED.has(k)) findings[k] = v
+  // `empty` keeps its reason as its finding.
+  if (check === 'empty' && typeof r.reason === 'string') findings.reason = r.reason
+  const outcome = String(r.outcome ?? 'unknown')
+  const known = OUTCOMES[outcome]
+  const drafts = Array.isArray(r.drafts) ? r.drafts : []
+  const firstDraft = clipDraft(r.firstDraft ?? r.draft ?? drafts[0])
+  const secondDraft = clipDraft(r.secondDraft ?? drafts[1])
+  const second = (r.secondCheck && typeof r.secondCheck === 'object' ? r.secondCheck : null) as Record<string, unknown> | null
+  const secondName = r.secondGuardrail ?? second?.guardrail ?? second?.check
+  const secondFindings = ((r.secondDetail ?? second?.findings ?? second?.detail) as Record<string, unknown> | undefined) ?? {}
+  return {
+    check,
+    found: foundBy(check, findings, r.reason),
+    findings,
+    outcome,
+    personGot: known?.got ?? `the runtime recorded the outcome "${outcome}"`,
+    replacedWithFixedReply: known?.fixedReply ?? false,
+    ...(typeof r.correction === 'string' ? { correction: r.correction } : {}),
+    ...(firstDraft ? { firstDraft } : {}),
+    ...(secondDraft ? { secondDraft } : {}),
+    ...(secondName ? { secondCheck: { check: String(secondName), found: foundBy(String(secondName), secondFindings, undefined), findings: secondFindings } } : {}),
+    ...(at ? { at } : {}),
+  }
+}
+
+const isReplyBlocked = (name: string) => /reply[._ -]?blocked/i.test(name)
+
+/** The reply checks a trace recorded (its `reply.blocked` spans), in order. */
+export function replyChecksOfTrace(observations: Array<{ name: string; startTime?: string | null; metadata?: Record<string, unknown> | null; statusMessage?: string | null }>): ReplyCheck[] {
+  return [...observations]
+    .filter((o) => isReplyBlocked(o.name))
+    .sort((a, b) => Date.parse(a.startTime ?? '') - Date.parse(b.startTime ?? ''))
+    .map((o) => replyCheckOf({ ...(o.statusMessage ? { reason: o.statusMessage } : {}), ...(o.metadata ?? {}) }, o.startTime))
+}

package/src/mcp/page-observation.ts

@@ -0,0 +1,193 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+
+import { RENDER_EVIDENCE_PATH, RENDER_THUMBNAIL_PATH } from '../render-evidence'
+import type { A11yResult } from './a11y-scan'
+
+/**
+ * What a page showed and said once it settled: the one shape both browsers
+ * answer with, Forge's Browser (the person watches it there) and the
+ * headless fallback. `app_render` turns it into render evidence.
+ */
+
+export interface ObserveRequest {
+  url: string
+  width?: number
+  height?: number
+  settleMs?: number
+  waitForText?: string
+  fullPage?: boolean
+  /** axe-core's script, to scan the page once it settles; no scan without it. */
+  a11yScript?: string | null
+  /** The expression that runs the scan, after the script (`AXE_RUN`). */
+  a11yRun?: string
+}
+
+export interface PageObservation {
+  /** The accessibility scan, when one ran. */
+  a11y?: A11yResult | null
+  url: string
+  title: string
+  /** The page's visible text, clipped. */
+  text: string
+  console: Array<{ level: 'error' | 'warning'; text: string }>
+  failedRequests: Array<{ url: string; method: string; reason: string }>
+  requests: Array<{ url: string; method: string; status: number; type?: string }>
+  navigationError: string | null
+  /** PNG, base64. */
+  screenshot: string
+  where: 'forge' | 'headless'
+  /** Forge's tab, so the person can find the page the agent rendered. */
+  tabId?: string
+}
+
+/** The Blueprint reads and governed Action requests the page made, from its requests. */
+export function platformCalls(requests: PageObservation['requests']) {
+  const path = (url: string) => {
+    try {
+      return new URL(url).pathname
+    } catch {
+      return url
+    }
+  }
+  const blueprint = requests
+    .filter((r) => /\/v1\/blueprint\//.test(path(r.url)) && !/\/governed-actions\//.test(path(r.url)))
+    .map((r) => ({ method: r.method, path: path(r.url), status: r.status }))
+  const actions = requests
+    .filter((r) => r.method === 'POST' && /\/v1\/blueprint\/governed-actions\/actions\/[^/]+\/requests$/.test(path(r.url)))
+    .map((r) => ({ action: decodeURIComponent(path(r.url).split('/').at(-2) ?? ''), status: r.status }))
+  const functions = requests
+    .filter((r) => /\/v1\/(functions|automations)\/[^/]+\/(invoke|run)/.test(path(r.url)))
+    .map((r) => ({ method: r.method, path: path(r.url), status: r.status }))
+  return { blueprint, actions, functions }
+}
+
+export interface RenderRecord {
+  renderedAt: string
+  renderedAtMs: number
+  path: string
+  title: string
+  consoleErrors: number
+  failedRequests: number
+  /** Where it rendered and against what: the evidence a reviewer weighs. */
+  source: 'frontera-mcp'
+  browser: 'forge' | 'headless'
+  runtime: { kind: 'local'; url: string; version: string | null } | { kind: 'url'; url: string }
+  /**
+   * What was rendered, for a deploy to check it is evidence of this App: its
+   * dev server, its own preview (`/apps/<slug>`), or an address that is
+   * neither (`elsewhere`), which a deploy does not attach.
+   */
+  target?: RenderTarget
+  blueprintCalls: number
+  actionRequests: number
+  /** The basic accessibility scan, when one ran: what a deployment's Accessibility check reads. */
+  a11y?: A11yResult
+}
+
+export interface RenderTarget {
+  of: 'dev-server' | 'preview' | 'elsewhere'
+  /** The address opened, without any session token. */
+  url: string
+  /** The App's slug it was rendered for. */
+  app: string
+}
+
+/**
+ * Whether an address `app_render` was given is this App's: under its running
+ * dev server, or one of its preview links (`/apps/<slug>`, any deployment).
+ */
+export function renderTargetOf(url: string, app: string, devServerUrl: string | null): RenderTarget {
+  let at: URL
+  try {
+    at = new URL(url)
+  } catch {
+    return { of: 'elsewhere', url, app }
+  }
+  if (devServerUrl) {
+    try {
+      if (new URL(devServerUrl).origin === at.origin) return { of: 'dev-server', url, app }
+    } catch {
+      // Not a URL: no dev server to compare with.
+    }
+  }
+  const segments = at.pathname.split('/').filter(Boolean)
+  const i = segments.indexOf('apps')
+  if (i >= 0 && decodeURIComponent(segments[i + 1] ?? '') === app) return { of: 'preview', url, app }
+  return { of: 'elsewhere', url, app }
+}
+
+const stamp = (d: Date) => d.toISOString().replace(/[:.]/g, '-')
+
+/**
+ * Write what `frontera app deploy` reads (`.frontera/last-render.json` and
+ * the screenshot beside it, in the App's folder) and keep a copy in the
+ * project's evidence folder, per session, for the person and a change
+ * request. Returns the evidence paths relative to the solution.
+ */
+export function writeRenderEvidence(args: {
+  appRoot: string
+  solutionRoot: string
+  session: string | null
+  slug: string
+  path: string
+  observation: PageObservation
+  runtime: RenderRecord['runtime']
+  target?: RenderTarget
+  now?: Date
+}): { record: RenderRecord; screenshot: string; evidence: string } {
+  const now = args.now ?? new Date()
+  const calls = platformCalls(args.observation.requests)
+  const record: RenderRecord = {
+    renderedAt: now.toISOString(),
+    renderedAtMs: now.getTime(),
+    path: args.path,
+    title: args.observation.title,
+    consoleErrors: args.observation.console.filter((c) => c.level === 'error').length,
+    failedRequests: args.observation.failedRequests.length,
+    source: 'frontera-mcp',
+    browser: args.observation.where,
+    runtime: args.runtime,
+    ...(args.target ? { target: args.target } : {}),
+    blueprintCalls: calls.blueprint.length,
+    actionRequests: calls.actions.length,
+    ...(args.observation.a11y ? { a11y: args.observation.a11y } : {}),
+  }
+  const png = Buffer.from(args.observation.screenshot, 'base64')
+  const evidenceFile = join(args.appRoot, RENDER_EVIDENCE_PATH)
+  mkdirSync(dirname(evidenceFile), { recursive: true })
+  writeFileSync(evidenceFile, `${JSON.stringify(record, null, 2)}\n`)
+  writeFileSync(join(args.appRoot, RENDER_THUMBNAIL_PATH), png)
+
+  const folder = evidenceDir(args.solutionRoot, args.session)
+  mkdirSync(folder, { recursive: true })
+  const base = `${stamp(now)}-${args.slug.replace(/[^a-z0-9-]+/gi, '-')}-render`
+  writeFileSync(join(folder, `${base}.png`), png)
+  writeFileSync(join(folder, `${base}.json`), `${JSON.stringify({ ...record, url: args.observation.url, console: args.observation.console, failed: args.observation.failedRequests, calls }, null, 2)}\n`)
+  return { record, screenshot: relative(args.solutionRoot, join(folder, `${base}.png`)), evidence: relative(args.solutionRoot, join(folder, `${base}.json`)) }
+}
+
+/** `.frontera/evidence/<session>/`: screenshots and render results, gitignored with the rest of `.frontera`'s local state. */
+export function evidenceDir(solutionRoot: string, session: string | null): string {
+  ignoreEvidence(solutionRoot)
+  return join(solutionRoot, '.frontera', 'evidence', (session ?? 'cli').replace(/[^a-z0-9-]+/gi, '-'))
+}
+
+/** Screenshots can show real records: they never reach git. */
+function ignoreEvidence(root: string): void {
+  const ignore = join(root, '.frontera', '.gitignore')
+  mkdirSync(dirname(ignore), { recursive: true })
+  const text = existsSync(ignore) ? readFileSync(ignore, 'utf8') : ''
+  if (text.split(/\r?\n/).some((l) => l.trim() === 'evidence/' || l.trim() === 'evidence')) return
+  if (text) appendFileSync(ignore, `${text.endsWith('\n') ? '' : '\n'}evidence/\n`)
+  else writeFileSync(ignore, 'local/\nevidence/\n')
+}
+
+/** Save a screenshot into the session's evidence folder; returns its path from the solution root. */
+export function saveScreenshot(solutionRoot: string, session: string | null, png: string, label: string, now = new Date()): string {
+  const folder = evidenceDir(solutionRoot, session)
+  mkdirSync(folder, { recursive: true })
+  const file = join(folder, `${stamp(now)}-${label.replace(/[^a-z0-9-]+/gi, '-').slice(0, 40) || 'page'}.png`)
+  writeFileSync(file, Buffer.from(png, 'base64'))
+  return relative(solutionRoot, file)
+}