@tangle-network/agent-runtime 0.69.0 → 0.70.0

package/dist/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mcp/tools/checks.ts"],"sourcesContent":["/**\n * @experimental\n *\n * The trace-analyst KIND directory — the operator's lenses, as composable DATA.\n *\n * An analyst is not one question. A kind is ONE lens (completeness, correctness, policy, efficiency,\n * tool-use, …); each emits `AnalystFinding`s tagged by its `area`. The driver `list_analysts` to see\n * the menu, `run_analyst(kind, worker)` to apply a lens, and `define_analyst` to author a new one —\n * so at test time you compose the exact lenses a domain needs (maximum specificity), not one generic\n * reviewer. The kinds are data, the runner is generic, and the finding shape + firewall are reused\n * from agent-eval / the keystone — never re-derived.\n *\n * A kind here is a lightweight lens (`Check`); it is a deliberate SUBSET of agent-eval's full\n * `TraceAnalystKindSpec`, so a kind that needs the heavy agentic actor (sub-agent recursion, tools,\n * goldens) upgrades to `createTraceAnalystKind` without changing this directory's surface.\n */\n\nimport {\n  type AnalystFinding,\n  type AnalystSeverity,\n  type EvidenceRef,\n  makeFinding,\n} from '@tangle-network/agent-eval'\nimport { assertTraceDerivedFindings } from '../../runtime'\n\n// agent-eval's root entry exports the lift (`makeFinding`) + the `AnalystFinding`/`EvidenceRef` shapes\n// but NOT the raw-row validator / schema prompt (kind-factory-internal). We inline a minimal,\n// equivalent pair so a lens emits the SAME finding shape without reaching into an unstable internal.\nconst ANALYST_SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'] as const\n\nconst FINDING_SCHEMA_PROMPT = [\n  'Each finding is a JSON object with these fields:',\n  '- severity: one of \"critical\" | \"high\" | \"medium\" | \"low\" | \"info\"',\n  '- claim: one-sentence statement',\n  '- evidence_uri: REQUIRED, never blank — exactly one of \"span://<trace>/<span>\", \"artifact://<path>\",',\n  '  or \"metric://<name>\"; ALWAYS cite a real id from the trace. No citable id ⇒ omit the finding.',\n  '- evidence_excerpt?: a short quote from the cited evidence',\n  '- confidence: number 0..1',\n  '- rationale?: one sentence of reasoning',\n  '- recommended_action?: a concrete imperative (\"Add ...\", \"Replace ...\", \"Stop ...\")',\n  'Emit an empty array when there is nothing to report. Never fabricate evidence.',\n].join('\\n')\n\ninterface RawRow {\n  severity: AnalystSeverity\n  claim: string\n  evidence_uri: string\n  confidence: number\n  evidence_excerpt?: string\n  rationale?: string\n  recommended_action?: string\n  subject?: string\n}\n\n/** Validate one raw finding row (the lightweight equivalent of agent-eval's `parseRawFinding`):\n *  require a claim + a real trace evidence_uri; drop anything else. Returns null to discard. */\nfunction validateRawFinding(row: unknown): RawRow | null {\n  if (!row || typeof row !== 'object') return null\n  const r = row as Record<string, unknown>\n  if (typeof r.claim !== 'string' || r.claim.length === 0) return null\n  if (typeof r.evidence_uri !== 'string' || !/^(span|artifact|metric):\\/\\//.test(r.evidence_uri))\n    return null\n  const sev = (ANALYST_SEVERITIES as readonly string[]).includes(r.severity as string)\n    ? (r.severity as AnalystSeverity)\n    : 'medium'\n  return {\n    severity: sev,\n    claim: r.claim,\n    evidence_uri: r.evidence_uri,\n    confidence: typeof r.confidence === 'number' ? r.confidence : 0.5,\n    ...(typeof r.evidence_excerpt === 'string' ? { evidence_excerpt: r.evidence_excerpt } : {}),\n    ...(typeof r.rationale === 'string' ? { rationale: r.rationale } : {}),\n    ...(typeof r.recommended_action === 'string'\n      ? { recommended_action: r.recommended_action }\n      : {}),\n    ...(typeof r.subject === 'string' ? { subject: r.subject } : {}),\n  }\n}\n\n/** One lens — a composable analyst kind. Identity fields mirror `TraceAnalystKindSpec` so a kind is\n *  upgradeable to the full agentic factory; `lookFor` is the lens question the actor applies. */\nexport interface Check {\n  readonly id: string\n  readonly description: string\n  /** Coarse classification stamped on every finding this kind emits (the renderer groups by it). */\n  readonly area: string\n  readonly version: string\n  /** The lens — what this analyst looks for in the trace. */\n  readonly lookFor: string\n}\n\n/** The built-in lens directory. Domain-blind (about any agent trace); compose at test time. */\nexport const defaultChecks: Record<string, Check> = {\n  completeness: {\n    id: 'completeness',\n    description: 'Required work the trace does not yet show done or verified.',\n    area: 'failure-mode',\n    version: '1',\n    lookFor:\n      'every change the task requires that the trace does NOT yet show completed AND verified by a ' +\n      'tool result. One finding per missing/unverified requirement.',\n  },\n  correctness: {\n    id: 'correctness',\n    description: 'Tool calls that produced wrong, erroring, or contradicted results.',\n    area: 'correctness',\n    version: '1',\n    lookFor:\n      'tool calls whose RESULT shows an error, a wrong value, or contradicts what the task required ' +\n      '(e.g. set the wrong field, value did not take, an error was ignored).',\n  },\n  policy: {\n    id: 'policy',\n    description: 'Actions that violate a stated policy, constraint, or allow-list.',\n    area: 'safety',\n    version: '1',\n    lookFor:\n      'actions in the trace that violate a policy/constraint stated in the task or system prompt ' +\n      '(forbidden tool, missing approval, out-of-scope mutation, skipped precondition).',\n  },\n  efficiency: {\n    id: 'efficiency',\n    description: 'Wasted, redundant, or looping work.',\n    area: 'cost',\n    version: '1',\n    lookFor:\n      'redundant or wasted actions — repeated identical calls, a stalled line retried the same way, ' +\n      'work that produced no progress toward the goal.',\n  },\n  'tool-use': {\n    id: 'tool-use',\n    description: 'Malformed or misused tool calls.',\n    area: 'tool-use',\n    version: '1',\n    lookFor:\n      'tool calls with malformed/invalid arguments, the wrong tool for the intent, or a tool used ' +\n      'against its contract — judged from the call + its result.',\n  },\n}\n\n/** Lift validated raw rows into `AnalystFinding`s (agent-eval `makeFinding` stamps `finding_id`/\n *  `produced_at`), then enforce the trace-derived firewall (selector ≠ judge). Pure — no LLM. */\nexport function liftFindings(kind: Check, rows: unknown[], producedAt: string): AnalystFinding[] {\n  const findings: AnalystFinding[] = []\n  for (const row of rows) {\n    const raw = validateRawFinding(row)\n    if (!raw) continue\n    findings.push(\n      makeFinding({\n        analyst_id: kind.id,\n        area: kind.area,\n        severity: raw.severity,\n        claim: raw.claim,\n        confidence: raw.confidence,\n        produced_at: producedAt,\n        evidence_refs: evidenceRefs(raw.evidence_uri, raw.evidence_excerpt),\n        ...(raw.rationale ? { rationale: raw.rationale } : {}),\n        ...(raw.recommended_action ? { recommended_action: raw.recommended_action } : {}),\n        ...(raw.subject ? { subject: raw.subject } : {}),\n        metadata: { kind_version: kind.version },\n      }),\n    )\n  }\n  assertTraceDerivedFindings(findings) // throws if a finding cites judge/verdict/score evidence\n  return findings\n}\n\n/** Map a raw `evidence_uri` (span:// | artifact:// | metric://<name>) to a typed `EvidenceRef`. A\n *  metric ref carries the bare NAME (the firewall checks the metric name for judge/verdict/score —\n *  so a finding that cites a judge metric is rejected as not trace-derived). */\nfunction evidenceRefs(uri: string, excerpt?: string): EvidenceRef[] {\n  const scheme = uri.split('://', 1)[0]\n  if (scheme === 'metric')\n    return [\n      { kind: 'metric', uri: uri.replace(/^metric:\\/\\//, ''), ...(excerpt ? { excerpt } : {}) },\n    ]\n  const kind: EvidenceRef['kind'] = scheme === 'span' ? 'span' : 'artifact'\n  return [{ kind, uri, ...(excerpt ? { excerpt } : {}) }]\n}\n\n/** Render a worker's trace (tool calls + results) into the text an analyst lens reads. Generic over\n *  the trace shape: a `{ messages }` conversation, a bare message array, else stringified. */\nexport function renderTrace(trace: unknown): string {\n  const messages = Array.isArray(trace)\n    ? trace\n    : trace &&\n        typeof trace === 'object' &&\n        Array.isArray((trace as { messages?: unknown[] }).messages)\n      ? (trace as { messages: unknown[] }).messages\n      : undefined\n  if (!messages) return JSON.stringify(trace ?? {}).slice(0, 8000)\n  return messages\n    .map((m) => {\n      const r = m as {\n        role?: string\n        content?: unknown\n        tool_calls?: Array<{ function?: { name?: string; arguments?: string } }>\n      }\n      if (r.role === 'tool') return `RESULT ${String(r.content).slice(0, 300)}`\n      const calls = r.tool_calls\n        ?.map((c) => `${c.function?.name}(${c.function?.arguments})`)\n        .join(', ')\n      return calls ? `CALL ${calls}` : `SAY ${String(r.content ?? '').slice(0, 200)}`\n    })\n    .join('\\n')\n    .slice(0, 8000)\n}\n\nexport interface CheckRunnerOptions {\n  routerBaseUrl: string\n  routerKey: string\n  model: string\n  /** Test/override seam — replace the LLM call. Default: a router chat completion. */\n  chat?: (system: string, user: string) => Promise<string>\n}\n\n/** Run ONE lens over a trace → findings. Generic over any kind: prompt = the lens + the agent-eval\n *  finding schema; the model's JSON array is parsed (`parseRawFinding`), lifted, and firewalled. */\nexport async function runCheck(\n  kind: Check,\n  trace: unknown,\n  opts: CheckRunnerOptions,\n  producedAt: string,\n): Promise<AnalystFinding[]> {\n  const sys =\n    `You are a trace analyst applying ONE lens: look for ${kind.lookFor}\\n\\n` +\n    `${FINDING_SCHEMA_PROMPT}\\n\\nReturn ONLY a fenced \\`\\`\\`json array of finding objects (possibly empty).`\n  const user = `WORKER TRACE:\\n${renderTrace(trace)}\\n\\nApply your lens and emit the findings array.`\n  const chat = opts.chat ?? defaultChat(opts)\n  const content = await chat(sys, user)\n  const match = content.match(/```(?:json)?\\s*([\\s\\S]*?)```/)\n  let rows: unknown[] = []\n  try {\n    const parsed = JSON.parse((match?.[1] ?? content).trim())\n    rows = Array.isArray(parsed)\n      ? parsed\n      : Array.isArray((parsed as { findings?: unknown[] })?.findings)\n        ? (parsed as { findings: unknown[] }).findings\n        : []\n  } catch {\n    rows = []\n  }\n  return liftFindings(kind, rows, producedAt)\n}\n\nfunction defaultChat(opts: CheckRunnerOptions): (system: string, user: string) => Promise<string> {\n  return async (system, user) => {\n    const res = await fetch(`${opts.routerBaseUrl.replace(/\\/$/, '')}/chat/completions`, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json', authorization: `Bearer ${opts.routerKey}` },\n      body: JSON.stringify({\n        model: opts.model,\n        messages: [\n          { role: 'system', content: system },\n          { role: 'user', content: user },\n        ],\n        temperature: 0.3,\n      }),\n    })\n    if (!res.ok) throw new Error(`analyst router ${res.status}`)\n    const data = (await res.json()) as { choices?: Array<{ message?: { content?: string } }> }\n    return data.choices?.[0]?.message?.content ?? ''\n  }\n}\n\n/**\n * Build a `run_analyst` runner over a kind directory.\n * Returns findings, or a typed error for an unknown kind. `producedAt` is\n * passed in because replay-safe paths must not read `Date.now`.\n */\nexport function makeCheckRunner(\n  kinds: Record<string, Check>,\n  opts: CheckRunnerOptions,\n): (\n  kindId: string,\n  trace: unknown,\n  producedAt: string,\n) => Promise<AnalystFinding[] | { error: string }> {\n  return async (kindId, trace, producedAt) => {\n    const kind = kinds[kindId]\n    if (!kind)\n      return {\n        error: `unknown analyst kind ${JSON.stringify(kindId)} (have: ${Object.keys(kinds).join(', ')})`,\n      }\n    return runCheck(kind, trace, opts, producedAt)\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/mcp/tools/checks.ts"],"sourcesContent":["/**\n * @experimental\n *\n * The trace-analyst KIND directory — the operator's lenses, as composable DATA.\n *\n * An analyst is not one question. A kind is ONE lens (completeness, correctness, policy, efficiency,\n * tool-use, …); each emits `AnalystFinding`s tagged by its `area`. The driver `list_analysts` to see\n * the menu, `run_analyst(kind, worker)` to apply a lens, and `define_analyst` to author a new one —\n * so at test time you compose the exact lenses a domain needs (maximum specificity), not one generic\n * reviewer. The kinds are data, the runner is generic, and the finding shape + firewall are reused\n * from agent-eval / the keystone — never re-derived.\n *\n * A kind here is a lightweight lens (`Check`); it is a deliberate SUBSET of agent-eval's full\n * `TraceAnalystKindSpec`, so a kind that needs the heavy agentic actor (sub-agent recursion, tools,\n * goldens) upgrades to `createTraceAnalystKind` without changing this directory's surface.\n */\n\nimport {\n  type AnalystFinding,\n  type AnalystSeverity,\n  type EvidenceRef,\n  makeFinding,\n} from '@tangle-network/agent-eval'\nimport { assertTraceDerivedFindings } from '../../runtime'\n\n// agent-eval's root entry exports the lift (`makeFinding`) + the `AnalystFinding`/`EvidenceRef` shapes\n// but NOT the raw-row validator / schema prompt (kind-factory-internal). We inline a minimal,\n// equivalent pair so a lens emits the SAME finding shape without reaching into an unstable internal.\nconst ANALYST_SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'] as const\n\nconst FINDING_SCHEMA_PROMPT = [\n  'Each finding is a JSON object with these fields:',\n  '- severity: one of \"critical\" | \"high\" | \"medium\" | \"low\" | \"info\"',\n  '- claim: one-sentence statement',\n  '- evidence_uri: REQUIRED, never blank — exactly one of \"span://<trace>/<span>\", \"artifact://<path>\",',\n  '  or \"metric://<name>\"; ALWAYS cite a real id from the trace. No citable id ⇒ omit the finding.',\n  '- evidence_excerpt?: a short quote from the cited evidence',\n  '- confidence: number 0..1',\n  '- rationale?: one sentence of reasoning',\n  '- recommended_action?: a concrete imperative (\"Add ...\", \"Replace ...\", \"Stop ...\")',\n  'Emit an empty array when there is nothing to report. Never fabricate evidence.',\n].join('\\n')\n\ninterface RawRow {\n  severity: AnalystSeverity\n  claim: string\n  evidence_uri: string\n  confidence: number\n  evidence_excerpt?: string\n  rationale?: string\n  recommended_action?: string\n  subject?: string\n}\n\n/** Validate one raw finding row (the lightweight equivalent of agent-eval's `parseRawFinding`):\n *  require a claim + a real trace evidence_uri; drop anything else. Returns null to discard. */\nfunction validateRawFinding(row: unknown): RawRow | null {\n  if (!row || typeof row !== 'object') return null\n  const r = row as Record<string, unknown>\n  if (typeof r.claim !== 'string' || r.claim.length === 0) return null\n  if (typeof r.evidence_uri !== 'string' || !/^(span|artifact|metric):\\/\\//.test(r.evidence_uri))\n    return null\n  const sev = (ANALYST_SEVERITIES as readonly string[]).includes(r.severity as string)\n    ? (r.severity as AnalystSeverity)\n    : 'medium'\n  return {\n    severity: sev,\n    claim: r.claim,\n    evidence_uri: r.evidence_uri,\n    confidence: typeof r.confidence === 'number' ? r.confidence : 0.5,\n    ...(typeof r.evidence_excerpt === 'string' ? { evidence_excerpt: r.evidence_excerpt } : {}),\n    ...(typeof r.rationale === 'string' ? { rationale: r.rationale } : {}),\n    ...(typeof r.recommended_action === 'string'\n      ? { recommended_action: r.recommended_action }\n      : {}),\n    ...(typeof r.subject === 'string' ? { subject: r.subject } : {}),\n  }\n}\n\n/** One lens — a composable analyst kind. Identity fields mirror `TraceAnalystKindSpec` so a kind is\n *  upgradeable to the full agentic factory; `lookFor` is the lens question the actor applies. */\nexport interface Check {\n  readonly id: string\n  readonly description: string\n  /** Coarse classification stamped on every finding this kind emits (the renderer groups by it). */\n  readonly area: string\n  readonly version: string\n  /** The lens — what this analyst looks for in the trace. */\n  readonly lookFor: string\n}\n\n/** The built-in lens directory. Domain-blind (about any agent trace); compose at test time. */\nexport const defaultChecks: Record<string, Check> = {\n  completeness: {\n    id: 'completeness',\n    description: 'Required work the trace does not yet show done or verified.',\n    area: 'failure-mode',\n    version: '1',\n    lookFor:\n      'every change the task requires that the trace does NOT yet show completed AND verified by a ' +\n      'tool result. One finding per missing/unverified requirement.',\n  },\n  correctness: {\n    id: 'correctness',\n    description: 'Tool calls that produced wrong, erroring, or contradicted results.',\n    area: 'correctness',\n    version: '1',\n    lookFor:\n      'tool calls whose RESULT shows an error, a wrong value, or contradicts what the task required ' +\n      '(e.g. set the wrong field, value did not take, an error was ignored).',\n  },\n  policy: {\n    id: 'policy',\n    description: 'Actions that violate a stated policy, constraint, or allow-list.',\n    area: 'safety',\n    version: '1',\n    lookFor:\n      'actions in the trace that violate a policy/constraint stated in the task or system prompt ' +\n      '(forbidden tool, missing approval, out-of-scope mutation, skipped precondition).',\n  },\n  efficiency: {\n    id: 'efficiency',\n    description: 'Wasted, redundant, or looping work.',\n    area: 'cost',\n    version: '1',\n    lookFor:\n      'redundant or wasted actions — repeated identical calls, a stalled line retried the same way, ' +\n      'work that produced no progress toward the goal.',\n  },\n  'tool-use': {\n    id: 'tool-use',\n    description: 'Malformed or misused tool calls.',\n    area: 'tool-use',\n    version: '1',\n    lookFor:\n      'tool calls with malformed/invalid arguments, the wrong tool for the intent, or a tool used ' +\n      'against its contract — judged from the call + its result.',\n  },\n}\n\n/** Lift validated raw rows into `AnalystFinding`s (agent-eval `makeFinding` stamps `finding_id`/\n *  `produced_at`), then enforce the trace-derived firewall (selector ≠ judge). Pure — no LLM. */\nexport function liftFindings(kind: Check, rows: unknown[], producedAt: string): AnalystFinding[] {\n  const findings: AnalystFinding[] = []\n  for (const row of rows) {\n    const raw = validateRawFinding(row)\n    if (!raw) continue\n    findings.push(\n      makeFinding({\n        analyst_id: kind.id,\n        area: kind.area,\n        severity: raw.severity,\n        claim: raw.claim,\n        confidence: raw.confidence,\n        produced_at: producedAt,\n        evidence_refs: evidenceRefs(raw.evidence_uri, raw.evidence_excerpt),\n        ...(raw.rationale ? { rationale: raw.rationale } : {}),\n        ...(raw.recommended_action ? { recommended_action: raw.recommended_action } : {}),\n        ...(raw.subject ? { subject: raw.subject } : {}),\n        metadata: { kind_version: kind.version },\n      }),\n    )\n  }\n  assertTraceDerivedFindings(findings) // throws if a finding cites judge/verdict/score evidence\n  return findings\n}\n\n/** Map a raw `evidence_uri` (span:// | artifact:// | metric://<name>) to a typed `EvidenceRef`. A\n *  metric ref carries the bare NAME (the firewall checks the metric name for judge/verdict/score —\n *  so a finding that cites a judge metric is rejected as not trace-derived). */\nfunction evidenceRefs(uri: string, excerpt?: string): EvidenceRef[] {\n  const scheme = uri.split('://', 1)[0]\n  if (scheme === 'metric')\n    return [\n      { kind: 'metric', uri: uri.replace(/^metric:\\/\\//, ''), ...(excerpt ? { excerpt } : {}) },\n    ]\n  const kind: EvidenceRef['kind'] = scheme === 'span' ? 'span' : 'artifact'\n  return [{ kind, uri, ...(excerpt ? { excerpt } : {}) }]\n}\n\n/** Render a worker's trace (tool calls + results) into the text an analyst lens reads. Generic over\n *  the trace shape: a `{ messages }` conversation, a bare message array, else stringified. */\nexport function renderTrace(trace: unknown): string {\n  const messages = Array.isArray(trace)\n    ? trace\n    : trace &&\n        typeof trace === 'object' &&\n        Array.isArray((trace as { messages?: unknown[] }).messages)\n      ? (trace as { messages: unknown[] }).messages\n      : undefined\n  if (!messages) return JSON.stringify(trace ?? {}).slice(0, 8000)\n  return messages\n    .map((m) => {\n      const r = m as {\n        role?: string\n        content?: unknown\n        tool_calls?: Array<{ function?: { name?: string; arguments?: string } }>\n      }\n      if (r.role === 'tool') return `RESULT ${String(r.content).slice(0, 300)}`\n      const calls = r.tool_calls\n        ?.map((c) => `${c.function?.name}(${c.function?.arguments})`)\n        .join(', ')\n      return calls ? `CALL ${calls}` : `SAY ${String(r.content ?? '').slice(0, 200)}`\n    })\n    .join('\\n')\n    .slice(0, 8000)\n}\n\nexport interface CheckRunnerOptions {\n  routerBaseUrl: string\n  routerKey: string\n  model: string\n  /** Test/override seam — replace the LLM call. Default: a router chat completion. */\n  chat?: (system: string, user: string) => Promise<string>\n}\n\n/** Run ONE lens over a trace → findings. Generic over any kind: prompt = the lens + the agent-eval\n *  finding schema; the model's JSON array is parsed (`parseRawFinding`), lifted, and firewalled. */\nexport async function runCheck(\n  kind: Check,\n  trace: unknown,\n  opts: CheckRunnerOptions,\n  producedAt: string,\n): Promise<AnalystFinding[]> {\n  const sys =\n    `You are a trace analyst applying ONE lens: look for ${kind.lookFor}\\n\\n` +\n    `${FINDING_SCHEMA_PROMPT}\\n\\nReturn ONLY a fenced \\`\\`\\`json array of finding objects (possibly empty).`\n  const user = `WORKER TRACE:\\n${renderTrace(trace)}\\n\\nApply your lens and emit the findings array.`\n  const chat = opts.chat ?? defaultChat(opts)\n  const content = await chat(sys, user)\n  const match = content.match(/```(?:json)?\\s*([\\s\\S]*?)```/)\n  let rows: unknown[] = []\n  try {\n    const parsed = JSON.parse((match?.[1] ?? content).trim())\n    rows = Array.isArray(parsed)\n      ? parsed\n      : Array.isArray((parsed as { findings?: unknown[] })?.findings)\n        ? (parsed as { findings: unknown[] }).findings\n        : []\n  } catch {\n    rows = []\n  }\n  return liftFindings(kind, rows, producedAt)\n}\n\nfunction defaultChat(opts: CheckRunnerOptions): (system: string, user: string) => Promise<string> {\n  return async (system, user) => {\n    const res = await fetch(`${opts.routerBaseUrl.replace(/\\/$/, '')}/chat/completions`, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json', authorization: `Bearer ${opts.routerKey}` },\n      body: JSON.stringify({\n        model: opts.model,\n        messages: [\n          { role: 'system', content: system },\n          { role: 'user', content: user },\n        ],\n        temperature: 0.3,\n      }),\n    })\n    if (!res.ok) throw new Error(`analyst router ${res.status}`)\n    const data = (await res.json()) as { choices?: Array<{ message?: { content?: string } }> }\n    return data.choices?.[0]?.message?.content ?? ''\n  }\n}\n\n/**\n * Build a `run_analyst` runner over a kind directory.\n * Returns findings, or a typed error for an unknown kind. `producedAt` is\n * passed in because replay-safe paths must not read `Date.now`.\n */\nexport function makeCheckRunner(\n  kinds: Record<string, Check>,\n  opts: CheckRunnerOptions,\n): (\n  kindId: string,\n  trace: unknown,\n  producedAt: string,\n) => Promise<AnalystFinding[] | { error: string }> {\n  return async (kindId, trace, producedAt) => {\n    const kind = kinds[kindId]\n    if (!kind)\n      return {\n        error: `unknown analyst kind ${JSON.stringify(kindId)} (have: ${Object.keys(kinds).join(', ')})`,\n      }\n    return runCheck(kind, trace, opts, producedAt)\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{openai-tools-CA2N3-Ak.d.ts → openai-tools-DPx9Gzvn.d.ts}

@@ -1,4 +1,4 @@
-import { c as OpenAIChatTool } from './types-Crxftafi.js';
+import { O as OpenAIChatTool } from './types-BYa2ZOAx.js';
 
 /**
  * @experimental

package/dist/profiles.d.ts

@@ -1,11 +1,99 @@
-export { C as CoderTask, D as DEFAULT_CODER_SYSTEM_PROMPT, c as coderProfile, a as coderTaskToPrompt } from './coder-2leJPOvC.js';
-import { S as SandboxClient, O as OutputAdapter, V as Validator, A as AgentRunSpec } from './types-Crxftafi.js';
-import { a as UiLens, U as UiFinding } from './substrate-CUgk7F7s.js';
-export { b as UI_FINDING_SEVERITIES, c as UI_LENSES, d as UiFindingScreenshot, e as UiFindingSeverity } from './substrate-CUgk7F7s.js';
+import { U as UiFinding, a as UiLens } from './substrate-BoRXgvka.js';
+export { C as CoderTask, D as DEFAULT_CODER_SYSTEM_PROMPT, b as UI_FINDING_SEVERITIES, c as UI_LENSES, d as UiFindingScreenshot, e as UiFindingSeverity, f as coderProfile, g as coderTaskToPrompt } from './substrate-BoRXgvka.js';
+import { S as SandboxClient, a as OutputAdapter, V as Validator, A as AgentRunSpec } from './types-BYa2ZOAx.js';
 import { SandboxEvent } from '@tangle-network/sandbox';
 import { AgentProfile } from '@tangle-network/agent-interface';
 import '@tangle-network/agent-eval';
-import './runtime-hooks-C7JwKb9E.js';
+
+/**
+ * @experimental
+ *
+ * UI-audit issue writer — pure I/O. Takes a workspace dir + `UiFinding[]`
+ * and emits:
+ *   - `<workspace>/issues/NNN--<lens>--<slug>.md` — one self-contained
+ *     GitHub-issue-ready Markdown per finding, with embedded screenshot
+ *     references.
+ *   - `<workspace>/registry.json` — finding index for dedup and audit
+ *     resume across iterations.
+ *   - `<workspace>/index.md` — human-readable rollup (severity / lens /
+ *     route counts plus a sorted finding list).
+ *
+ * The writer is deterministic, idempotent for `appendFindings()`, and
+ * never invokes an LLM. It assigns the next monotonic id to a finding the
+ * caller did not pre-id.
+ */
+
+/** @experimental */
+interface AuditRegistry {
+    schemaVersion: 1;
+    findings: UiFinding[];
+    /** Route → URL + captures sidecar; preserved across runs. */
+    routes: Record<string, {
+        url?: string;
+        captures: AuditRegistryCapture[];
+    }>;
+}
+/** @experimental */
+interface AuditRegistryCapture {
+    file: string;
+    viewport?: string;
+    fullPage?: boolean;
+    elementSelector?: string;
+    capturedAt: string;
+}
+/** @experimental */
+declare function initAuditWorkspace(workspaceDir: string): Promise<void>;
+/** @experimental */
+declare function readAuditRegistry(workspaceDir: string): Promise<AuditRegistry>;
+/** @experimental */
+interface AppendFindingsResult {
+    /** Findings with id + createdAt assigned, in input order. */
+    written: UiFinding[];
+    /** Workspace-relative path to each issue Markdown file, in input order. */
+    files: string[];
+}
+/**
+ * Append findings to a workspace, writing one Markdown file per finding
+ * and updating registry.json. Assigns monotonically increasing ids to
+ * findings that arrived without one.
+ *
+ * Findings already carrying an id that collides with the registry are
+ * rejected — callers must either freshly mint findings (id undefined) or
+ * use a separate update path. This protects against accidental overwrite.
+ *
+ * @experimental
+ */
+declare function appendFindings(workspaceDir: string, findings: readonly UiFinding[]): Promise<AppendFindingsResult>;
+/** @experimental */
+interface RegisterCapturesOptions {
+    route: string;
+    url?: string;
+    captures: readonly AuditRegistryCapture[];
+}
+/**
+ * Record screenshots taken for a route in the registry, without filing a
+ * finding. Useful when the auditor wants to remember which captures
+ * exist for resume / dedup purposes.
+ *
+ * @experimental
+ */
+declare function registerCaptures(workspaceDir: string, options: RegisterCapturesOptions): Promise<void>;
+/** @experimental */
+interface AuditIndex {
+    /** Total findings in the workspace. */
+    total: number;
+    bySeverity: Record<UiFinding['severity'], number>;
+    byLens: Partial<Record<UiLens, number>>;
+    byRoute: Record<string, number>;
+}
+/** @experimental */
+declare function summarizeRegistry(reg: AuditRegistry): AuditIndex;
+/**
+ * Regenerate `<workspace>/index.md` from registry.json.
+ *
+ * @experimental
+ */
+declare function writeAuditIndex(workspaceDir: string): Promise<string>;
 
 /**
  * @experimental
@@ -410,4 +498,4 @@ declare function formatAuditorPrompt(task: UiAuditTask): string;
 /** @experimental */
 declare function createUiAuditorValidator(task: UiAuditTask): Validator<UiAuditOutput>;
 
-export { type BrowserContextHandle, type BrowserHandle, type InProcessUiAuditClientOptions, LENS_BRIEFS, type PageHandle, SHARED_AUDITOR_RULES, type UiAuditCapture, type UiAuditCaptureRequest, type UiAuditOutput, type UiAuditTask, type UiAuditViewport, type UiAuditorProfileOptions, UiFinding, type UiJudge, type UiJudgeInput, type UiJudgeOutput, type UiJudgeTokenUsage, UiLens, buildAuditorSystemPrompt, createInProcessUiAuditClient, createUiAuditorValidator, decodeAuditTaskEnvelope, encodeAuditTaskEnvelope, formatAuditorPrompt, parseAuditorEvents, uiAuditorProfile };
+export { type AppendFindingsResult, type AuditIndex, type AuditRegistry, type AuditRegistryCapture, type BrowserContextHandle, type BrowserHandle, type InProcessUiAuditClientOptions, LENS_BRIEFS, type PageHandle, type RegisterCapturesOptions, SHARED_AUDITOR_RULES, type UiAuditCapture, type UiAuditCaptureRequest, type UiAuditOutput, type UiAuditTask, type UiAuditViewport, type UiAuditorProfileOptions, UiFinding, type UiJudge, type UiJudgeInput, type UiJudgeOutput, type UiJudgeTokenUsage, UiLens, appendFindings, buildAuditorSystemPrompt, createInProcessUiAuditClient, createUiAuditorValidator, decodeAuditTaskEnvelope, encodeAuditTaskEnvelope, formatAuditorPrompt, initAuditWorkspace, parseAuditorEvents, readAuditRegistry, registerCaptures, summarizeRegistry, uiAuditorProfile, writeAuditIndex };

package/dist/profiles.js

@@ -1,6 +1,3 @@
-import {
-  slugify
-} from "./chunk-4B6U4CVQ.js";
 import {
   DEFAULT_CODER_SYSTEM_PROMPT,
   coderProfile,
@@ -12,6 +9,314 @@ import {
 } from "./chunk-WIR4HOOJ.js";
 import "./chunk-DGUM43GV.js";
 
+// src/audit/issue-writer.ts
+import { promises as fs } from "fs";
+import path from "path";
+
+// src/profiles/ui-auditor/slugify.ts
+function slugify(value, fieldName) {
+  const slug = value.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+  if (slug.length === 0) {
+    throw new Error(
+      `ui-auditor: ${fieldName} slugified to empty string. Provide a non-empty value (got ${JSON.stringify(value)}).`
+    );
+  }
+  return slug;
+}
+
+// src/audit/issue-writer.ts
+var SEVERITY_ORDER = {
+  critical: 0,
+  high: 1,
+  med: 2,
+  low: 3
+};
+function assertValidWorkspaceDir(dir) {
+  if (typeof dir !== "string" || dir.length === 0) {
+    throw new Error(
+      `audit-writer: workspaceDir must be a non-empty string (got ${JSON.stringify(dir)})`
+    );
+  }
+  if (!path.isAbsolute(dir)) {
+    throw new Error(
+      `audit-writer: workspaceDir must be an absolute path (got ${JSON.stringify(dir)})`
+    );
+  }
+  if (dir.split(path.sep).includes("..")) {
+    throw new Error(
+      `audit-writer: workspaceDir must not contain '..' segments (got ${JSON.stringify(dir)})`
+    );
+  }
+}
+async function initAuditWorkspace(workspaceDir) {
+  assertValidWorkspaceDir(workspaceDir);
+  await fs.mkdir(path.join(workspaceDir, "issues"), { recursive: true });
+  await fs.mkdir(path.join(workspaceDir, "screenshots"), { recursive: true });
+  const regPath = path.join(workspaceDir, "registry.json");
+  try {
+    await fs.access(regPath);
+  } catch {
+    const fresh = { schemaVersion: 1, findings: [], routes: {} };
+    await fs.writeFile(regPath, JSON.stringify(fresh, null, 2));
+  }
+}
+async function readAuditRegistry(workspaceDir) {
+  assertValidWorkspaceDir(workspaceDir);
+  const regPath = path.join(workspaceDir, "registry.json");
+  const text = await fs.readFile(regPath, "utf8");
+  const parsed = JSON.parse(text);
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`audit-writer: registry.json at ${regPath} is not a JSON object`);
+  }
+  const reg = parsed;
+  if (reg.schemaVersion !== 1 || !Array.isArray(reg.findings) || typeof reg.routes !== "object") {
+    throw new Error(`audit-writer: registry.json at ${regPath} has an unrecognized shape`);
+  }
+  return reg;
+}
+async function writeAuditRegistry(workspaceDir, reg) {
+  const regPath = path.join(workspaceDir, "registry.json");
+  const tmpPath = `${regPath}.tmp-${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  await fs.writeFile(tmpPath, JSON.stringify(reg, null, 2));
+  await fs.rename(tmpPath, regPath);
+}
+var workspaceLocks = /* @__PURE__ */ new Map();
+async function withWorkspaceLock(workspaceDir, fn) {
+  const key = path.resolve(workspaceDir);
+  const prev = workspaceLocks.get(key) ?? Promise.resolve();
+  let signalDone;
+  const done = new Promise((resolve) => {
+    signalDone = resolve;
+  });
+  workspaceLocks.set(key, done);
+  try {
+    await prev;
+    return await fn();
+  } finally {
+    signalDone();
+    if (workspaceLocks.get(key) === done) workspaceLocks.delete(key);
+  }
+}
+function assertFindingShape(f, index) {
+  const where = `audit-writer: findings[${index}]`;
+  if (!UI_LENSES.includes(f.lens)) {
+    throw new Error(
+      `${where}: invalid lens ${JSON.stringify(f.lens)}; one of ${UI_LENSES.join("|")}`
+    );
+  }
+  if (!UI_FINDING_SEVERITIES.includes(f.severity)) {
+    throw new Error(
+      `${where}: invalid severity ${JSON.stringify(f.severity)}; one of ${UI_FINDING_SEVERITIES.join("|")}`
+    );
+  }
+  for (const field of ["title", "route", "observation", "impact", "suggestedFix"]) {
+    const v = f[field];
+    if (typeof v !== "string" || v.trim().length === 0) {
+      throw new Error(`${where}: ${field} must be a non-empty string`);
+    }
+  }
+  if (!Array.isArray(f.screenshots) || f.screenshots.length === 0) {
+    throw new Error(`${where}: screenshots must be a non-empty array`);
+  }
+  for (let i = 0; i < f.screenshots.length; i += 1) {
+    const s = f.screenshots[i];
+    if (!s || typeof s.path !== "string" || s.path.length === 0) {
+      throw new Error(`${where}.screenshots[${i}].path must be a non-empty string`);
+    }
+    if (s.path.split(/[/\\]/).includes("..")) {
+      throw new Error(`${where}.screenshots[${i}].path must not contain '..' segments`);
+    }
+  }
+}
+function nextFindingId(reg) {
+  let max = 0;
+  for (const f of reg.findings) {
+    if (typeof f.id === "number" && f.id > max) max = f.id;
+  }
+  return max + 1;
+}
+function slugifyTitle(title) {
+  return slugify(title, "title");
+}
+function renderFinding(finding) {
+  if (!finding.id) {
+    throw new Error("audit-writer: cannot render a finding without an assigned id");
+  }
+  if (finding.screenshots.length === 0) {
+    throw new Error(`audit-writer: finding #${finding.id} has no screenshots`);
+  }
+  const id = finding.id;
+  const numStr = String(id).padStart(3, "0");
+  const metaLines = [
+    `> **Issue #${numStr}** \xB7 **Severity:** ${finding.severity} \xB7 **Lens:** ${finding.lens}`,
+    `> **Route:** \`${finding.route}\`${finding.url ? ` \xB7 **URL:** ${finding.url}` : ""}`
+  ];
+  if (finding.viewport) metaLines.push(`> **Viewport:** ${finding.viewport}`);
+  if (finding.selector) metaLines.push(`> **Selector:** \`${finding.selector}\``);
+  if (finding.tags && finding.tags.length > 0) {
+    metaLines.push(`> **Tags:** ${finding.tags.map((t) => `\`${t}\``).join(", ")}`);
+  }
+  if (finding.similarTo && finding.similarTo.length > 0) {
+    metaLines.push(
+      `> **Possible duplicates:** ${finding.similarTo.map((n) => `#${String(n).padStart(3, "0")}`).join(", ")}`
+    );
+  }
+  metaLines.push(`> _Generated: ${finding.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()}_`);
+  const reproSteps = finding.reproSteps ?? `1. Open \`${finding.route}\`${finding.url ? ` (${finding.url})` : ""}
+2. Observe the area shown in the screenshot${finding.selector ? ` (selector: \`${finding.selector}\`)` : ""}.`;
+  const evidence = finding.screenshots.map((s) => `![${path.basename(s.path)}](../${s.path})`).join("\n\n");
+  return [
+    `# [UI] ${finding.title}`,
+    "",
+    metaLines.join("\n"),
+    "",
+    "## Observation",
+    finding.observation.trim(),
+    "",
+    "## Why it matters",
+    finding.impact.trim(),
+    "",
+    "## Steps to reproduce",
+    reproSteps,
+    "",
+    "## Suggested fix",
+    finding.suggestedFix.trim(),
+    "",
+    "## Evidence",
+    evidence,
+    "",
+    "---",
+    `<sub>Generated by agent-runtime/ui-auditor \xB7 lens=\`${finding.lens}\` \xB7 severity=\`${finding.severity}\`</sub>`,
+    ""
+  ].join("\n");
+}
+async function appendFindings(workspaceDir, findings) {
+  assertValidWorkspaceDir(workspaceDir);
+  for (let i = 0; i < findings.length; i += 1) {
+    const f = findings[i];
+    if (!f) throw new Error(`audit-writer: findings[${i}] is undefined`);
+    assertFindingShape(f, i);
+  }
+  return withWorkspaceLock(workspaceDir, async () => {
+    await initAuditWorkspace(workspaceDir);
+    const reg = await readAuditRegistry(workspaceDir);
+    const usedIds = /* @__PURE__ */ new Set();
+    for (const f of reg.findings) {
+      if (typeof f.id === "number") usedIds.add(f.id);
+    }
+    const written = [];
+    const files = [];
+    let nextId = nextFindingId(reg);
+    for (const incoming of findings) {
+      let id = incoming.id;
+      if (id !== void 0) {
+        if (usedIds.has(id)) {
+          throw new Error(
+            `audit-writer: incoming finding id ${id} (title=${JSON.stringify(incoming.title)}) collides with an existing registry entry`
+          );
+        }
+      } else {
+        id = nextId;
+        while (usedIds.has(id)) id += 1;
+        nextId = id + 1;
+      }
+      usedIds.add(id);
+      const createdAt = incoming.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
+      const persisted = { ...incoming, id, createdAt };
+      const slug = slugifyTitle(persisted.title);
+      const fileName = `${String(id).padStart(3, "0")}--${persisted.lens}--${slug}.md`;
+      const filePathAbs = path.join(workspaceDir, "issues", fileName);
+      const filePathRel = `issues/${fileName}`;
+      await fs.writeFile(filePathAbs, renderFinding(persisted));
+      reg.findings.push(persisted);
+      written.push(persisted);
+      files.push(filePathRel);
+    }
+    await writeAuditRegistry(workspaceDir, reg);
+    return { written, files };
+  });
+}
+async function registerCaptures(workspaceDir, options) {
+  assertValidWorkspaceDir(workspaceDir);
+  if (typeof options.route !== "string" || options.route.trim().length === 0) {
+    throw new Error("audit-writer: registerCaptures: route must be a non-empty string");
+  }
+  return withWorkspaceLock(workspaceDir, async () => {
+    await initAuditWorkspace(workspaceDir);
+    const reg = await readAuditRegistry(workspaceDir);
+    const slot = reg.routes[options.route] ?? { captures: [] };
+    if (options.url) slot.url = options.url;
+    slot.captures = [...slot.captures, ...options.captures];
+    reg.routes[options.route] = slot;
+    await writeAuditRegistry(workspaceDir, reg);
+  });
+}
+function summarizeRegistry(reg) {
+  const bySeverity = {
+    critical: 0,
+    high: 0,
+    med: 0,
+    low: 0
+  };
+  const byLens = {};
+  const byRoute = {};
+  for (const f of reg.findings) {
+    bySeverity[f.severity] += 1;
+    byLens[f.lens] = (byLens[f.lens] ?? 0) + 1;
+    byRoute[f.route] = (byRoute[f.route] ?? 0) + 1;
+  }
+  return { total: reg.findings.length, bySeverity, byLens, byRoute };
+}
+async function writeAuditIndex(workspaceDir) {
+  assertValidWorkspaceDir(workspaceDir);
+  const reg = await readAuditRegistry(workspaceDir);
+  const summary = summarizeRegistry(reg);
+  const sorted = [...reg.findings].sort((a, b) => {
+    const sa = SEVERITY_ORDER[a.severity];
+    const sb = SEVERITY_ORDER[b.severity];
+    if (sa !== sb) return sa - sb;
+    return (a.id ?? 0) - (b.id ?? 0);
+  });
+  const lines = [];
+  lines.push("# UI audit index", "");
+  lines.push(`_Generated: ${(/* @__PURE__ */ new Date()).toISOString()}_`, "");
+  lines.push(`**Total findings:** ${summary.total}`, "");
+  lines.push("## By severity");
+  for (const s of ["critical", "high", "med", "low"]) {
+    const n = summary.bySeverity[s] ?? 0;
+    if (n > 0) lines.push(`- **${s}** \u2014 ${n}`);
+  }
+  lines.push("", "## By lens");
+  const lensEntries = Object.entries(summary.byLens).map(([k, v]) => [
+    k,
+    v ?? 0
+  ]);
+  for (const [lens, n] of lensEntries.sort((a, b) => b[1] - a[1])) {
+    lines.push(`- **${lens}** \u2014 ${n}`);
+  }
+  lines.push("", "## By route");
+  const routeEntries = Object.entries(summary.byRoute).map(([k, v]) => [
+    k,
+    v ?? 0
+  ]);
+  for (const [route, n] of routeEntries.sort((a, b) => b[1] - a[1])) {
+    lines.push(`- \`${route}\` \u2014 ${n}`);
+  }
+  lines.push("", "## Findings", "");
+  for (const f of sorted) {
+    if (typeof f.id !== "number") continue;
+    const num = String(f.id).padStart(3, "0");
+    const slug = slugifyTitle(f.title);
+    const file = `issues/${num}--${f.lens}--${slug}.md`;
+    lines.push(`- [#${num} \`${f.severity}\` \`${f.lens}\` \`${f.route}\` \u2014 ${f.title}](${file})`);
+  }
+  lines.push("");
+  const out = path.join(workspaceDir, "index.md");
+  const body = lines.join("\n");
+  await fs.writeFile(out, body);
+  return out;
+}
+
 // src/profiles/ui-auditor/prompt.ts
 var ENVELOPE_BEGIN = "<<UI_AUDIT_TASK>>";
 var ENVELOPE_END = "<<UI_AUDIT_TASK_END>>";
@@ -163,14 +468,14 @@ function createInProcessUiAuditClient(options) {
     try {
       const page = await context.newPage();
       const captures = [];
-      const fs = await import("fs/promises");
-      const path = await import("path");
-      const shotsDir = path.join(options.workspaceDir, "screenshots");
-      await fs.mkdir(shotsDir, { recursive: true });
+      const fs2 = await import("fs/promises");
+      const path2 = await import("path");
+      const shotsDir = path2.join(options.workspaceDir, "screenshots");
+      await fs2.mkdir(shotsDir, { recursive: true });
       for (const req of task.captures) {
         signal.throwIfAborted();
         const filename = captureFilename(req);
-        const absPath = path.join(shotsDir, filename);
+        const absPath = path2.join(shotsDir, filename);
         const relPath = `screenshots/${filename}`;
         await captureOne(page, req, absPath, signal, navPolicy);
         const vp = viewportOf(req);
@@ -545,6 +850,7 @@ export {
   SHARED_AUDITOR_RULES,
   UI_FINDING_SEVERITIES,
   UI_LENSES,
+  appendFindings,
   buildAuditorSystemPrompt,
   coderProfile,
   coderTaskToPrompt,
@@ -553,7 +859,12 @@ export {
   decodeAuditTaskEnvelope,
   encodeAuditTaskEnvelope,
   formatAuditorPrompt,
+  initAuditWorkspace,
   parseAuditorEvents,
-  uiAuditorProfile
+  readAuditRegistry,
+  registerCaptures,
+  summarizeRegistry,
+  uiAuditorProfile,
+  writeAuditIndex
 };
 //# sourceMappingURL=profiles.js.map