@tangle-network/traces 0.23.1 → 1.0.1

package/dist/chunk-QUHUMZ4W.js

@@ -0,0 +1,759 @@
+import {
+  createFindingRejectionTally,
+  formatFindingRejections,
+  totalFindingRejections
+} from "./chunk-PYH3PL3N.js";
+import {
+  ASK_QUESTION_HEADER,
+  DEFAULT_ASK_CONCURRENCY,
+  MAX_TRACE_QUESTION_CHARS,
+  QUESTION_LABEL
+} from "./chunk-O52XK7OB.js";
+import {
+  exportBytes,
+  openAgenticTraceStore
+} from "./chunk-2XXABIRL.js";
+import {
+  createSessionFactsReportBuilder,
+  renderSessionFactsContext
+} from "./chunk-WF7PTDCZ.js";
+import {
+  indexSessionIdsByTrace
+} from "./chunk-UQSAGXPH.js";
+import {
+  appendAll
+} from "./chunk-CQ6UYZG6.js";
+
+// src/ask.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+import { performance } from "perf_hooks";
+import { CostCeilingReachedError, CostLedger } from "@tangle-network/agent-eval";
+import {
+  defineTraceAnalyst,
+  runTraceAnalyst
+} from "@tangle-network/agent-eval/analyst";
+
+// src/answer-schema.ts
+var SUPPORTED_KEYWORDS = /* @__PURE__ */ new Set([
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "enum",
+  "const",
+  "title",
+  "description"
+]);
+var JSON_TYPES = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean", "object", "array", "null"]);
+var MAX_SCHEMA_DEPTH = 32;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertAnswerSchema(schema, path = "answerSchema", depth = 0) {
+  if (depth > MAX_SCHEMA_DEPTH) throw new TypeError(`${path}: schema nesting exceeds ${MAX_SCHEMA_DEPTH} levels`);
+  if (!isRecord(schema)) throw new TypeError(`${path} must be a JSON Schema object`);
+  for (const key of Object.keys(schema)) {
+    if (!SUPPORTED_KEYWORDS.has(key)) {
+      throw new TypeError(
+        `${path}: unsupported JSON Schema keyword "${key}"; supported: ${[...SUPPORTED_KEYWORDS].join(", ")}`
+      );
+    }
+  }
+  if (schema.type !== void 0) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (types.length === 0 || !types.every((type) => typeof type === "string" && JSON_TYPES.has(type))) {
+      throw new TypeError(`${path}.type must be one of ${[...JSON_TYPES].join(", ")}, or an array of them`);
+    }
+  }
+  const declared = schema.type === void 0 ? void 0 : Array.isArray(schema.type) ? schema.type : [schema.type];
+  for (const keyword of ["properties", "required", "additionalProperties"]) {
+    if (schema[keyword] !== void 0 && !declared?.includes("object")) {
+      throw new TypeError(`${path}: "${keyword}" is checked only for an object; declare "type": "object" alongside it`);
+    }
+  }
+  if (schema.items !== void 0 && !declared?.includes("array")) {
+    throw new TypeError(`${path}: "items" is checked only for an array; declare "type": "array" alongside it`);
+  }
+  if (schema.properties !== void 0) {
+    if (!isRecord(schema.properties)) throw new TypeError(`${path}.properties must be an object`);
+    for (const [name, child] of Object.entries(schema.properties)) {
+      assertAnswerSchema(child, `${path}.properties.${name}`, depth + 1);
+    }
+  }
+  if (schema.required !== void 0) {
+    if (!Array.isArray(schema.required) || !schema.required.every((name) => typeof name === "string")) {
+      throw new TypeError(`${path}.required must be an array of property names`);
+    }
+  }
+  if (schema.additionalProperties !== void 0 && typeof schema.additionalProperties !== "boolean") {
+    throw new TypeError(`${path}.additionalProperties must be a boolean`);
+  }
+  if (schema.items !== void 0) assertAnswerSchema(schema.items, `${path}.items`, depth + 1);
+  if (schema.enum !== void 0 && (!Array.isArray(schema.enum) || schema.enum.length === 0)) {
+    throw new TypeError(`${path}.enum must be a non-empty array`);
+  }
+  for (const key of ["title", "description"]) {
+    if (schema[key] !== void 0 && typeof schema[key] !== "string") {
+      throw new TypeError(`${path}.${key} must be a string`);
+    }
+  }
+}
+function jsonType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  return typeof value;
+}
+function typeMatches(value, type) {
+  const actual = jsonType(value);
+  return actual === type || type === "number" && actual === "integer";
+}
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function answerSchemaErrors(value, schema, path = "$") {
+  const errors = [];
+  if (schema.type !== void 0) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((type) => typeMatches(value, type))) {
+      errors.push(`${path}: expected ${types.join(" or ")}, got ${jsonType(value)}`);
+      return errors;
+    }
+  }
+  if (schema.const !== void 0 && !sameJson(value, schema.const)) {
+    errors.push(`${path}: expected ${JSON.stringify(schema.const)}`);
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((option) => sameJson(value, option))) {
+    errors.push(`${path}: expected one of ${schema.enum.map((option) => JSON.stringify(option)).join(", ")}`);
+  }
+  if (isRecord(value)) {
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    for (const name of schema.required ?? []) {
+      if (!(name in value)) errors.push(`${path}.${name}: required property is missing`);
+    }
+    for (const [name, child] of Object.entries(value)) {
+      const childSchema = properties[name];
+      if (childSchema !== void 0) {
+        errors.push(...answerSchemaErrors(child, childSchema, `${path}.${name}`));
+      } else if (schema.additionalProperties === false) {
+        errors.push(`${path}.${name}: property is not allowed`);
+      }
+    }
+  }
+  if (Array.isArray(value) && schema.items !== void 0) {
+    value.forEach((entry, index) => {
+      errors.push(...answerSchemaErrors(entry, schema.items, `${path}[${index}]`));
+    });
+  }
+  return errors;
+}
+function parseJsonAnswer(text) {
+  const trimmed = text.trim();
+  const candidates = [trimmed];
+  const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n```$/.exec(trimmed);
+  if (fenced) candidates.push(fenced[1].trim());
+  for (const candidate of candidates) {
+    try {
+      return { ok: true, value: JSON.parse(candidate) };
+    } catch {
+    }
+  }
+  return { ok: false, error: "answer is not one JSON value" };
+}
+
+// src/ask.ts
+var BRIDGE_MISMATCH_PATTERN = /must contain exactly|No module named ['"]?agent_eval_rpc|could not start/;
+function isBridgeMismatchError(message) {
+  return BRIDGE_MISMATCH_PATTERN.test(message);
+}
+var ASK_DEFINITION_VERSION = "1.1.0";
+var ASK_RULES = [
+  "TRACES ASK RULES",
+  "1. Answer QUESTION only from trace tool results of this run.",
+  "2. PREPARED CONTEXT ends analyst_instructions: the trace list JSON, then a SESSION FACTS sheet. Copy IDs from both.",
+  // The rules must fit the DSPy preview head, so this one does not also legislate
+  // formatting: `traceCitationsInText` reads a citation the model emphasised.
+  "3. Cite each fact as trace://<trace_id>/span/<span_id>: span ids the sheet names, never the sheet.",
+  "4. Quote excerpts from viewSpans output, never searchTrace hits.",
+  '5. If the trace does not record a fact, say "not in trace".'
+].join("\n");
+var ANSWER_SCHEMA_RULE = "6. Answer with one JSON value matching ANSWER SCHEMA below, nothing else.";
+var MAX_CONTEXT_TRACES = 200;
+var QUESTION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+var QUESTION_KEYS = /* @__PURE__ */ new Set(["id", "question", "instructions", "answerSchema"]);
+function defaultQuestionId(index, reserved, taken) {
+  let n = index + 1;
+  while (reserved.has(`q${n}`) || taken.has(`q${n}`)) n += 1;
+  return `q${n}`;
+}
+function normalizeTraceQuestions(questions) {
+  if (questions.length === 0) throw new Error("ask needs at least one question");
+  const reserved = new Set(questions.flatMap((entry) => typeof entry.id === "string" ? [entry.id] : []));
+  const seen = /* @__PURE__ */ new Set();
+  return questions.map((entry, index) => {
+    const id = entry.id ?? defaultQuestionId(index, reserved, seen);
+    if (!QUESTION_ID.test(id)) {
+      throw new Error(`question ID "${id}" must match ${QUESTION_ID} (letters, digits, dot, underscore, hyphen)`);
+    }
+    if (seen.has(id)) throw new Error(`duplicate question ID "${id}"`);
+    seen.add(id);
+    const question = typeof entry.question === "string" ? entry.question.trim() : "";
+    if (!question) throw new Error(`question ${id} is empty`);
+    if (question.length > MAX_TRACE_QUESTION_CHARS) {
+      throw new Error(
+        `question ${id} has ${question.length} characters; the limit is ${MAX_TRACE_QUESTION_CHARS} so the model sees it whole. Move detail into the entry's "instructions" field.`
+      );
+    }
+    if (entry.instructions !== void 0 && typeof entry.instructions !== "string") {
+      throw new Error(`question ${id}: instructions must be a string`);
+    }
+    if (entry.answerSchema !== void 0) assertAnswerSchema(entry.answerSchema, `question ${id} answerSchema`);
+    return {
+      id,
+      question,
+      ...entry.instructions?.trim() ? { instructions: entry.instructions.trim() } : {},
+      ...entry.answerSchema !== void 0 ? { answerSchema: entry.answerSchema } : {}
+    };
+  });
+}
+async function loadTraceQuestionsFile(path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    throw new Error(`questions file ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const list = Array.isArray(parsed) ? parsed : typeof parsed === "object" && parsed !== null && Array.isArray(parsed.questions) ? parsed.questions : void 0;
+  if (!list) throw new Error(`questions file ${path} must hold a JSON array or an object with a "questions" array`);
+  return list.map((entry, index) => {
+    if (typeof entry === "string") return { question: entry };
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      throw new Error(`questions file ${path}: entry ${index + 1} must be a string or an object`);
+    }
+    for (const key of Object.keys(entry)) {
+      if (!QUESTION_KEYS.has(key)) {
+        throw new Error(`questions file ${path}: entry ${index + 1} has unknown key "${key}"`);
+      }
+    }
+    const record = entry;
+    if (typeof record.question !== "string") {
+      throw new Error(`questions file ${path}: entry ${index + 1} needs a "question" string`);
+    }
+    if (record.id !== void 0 && typeof record.id !== "string") {
+      throw new Error(`questions file ${path}: entry ${index + 1} "id" must be a string`);
+    }
+    return {
+      question: record.question,
+      ...record.id !== void 0 ? { id: record.id } : {},
+      ...record.instructions !== void 0 ? { instructions: record.instructions } : {},
+      ...record.answerSchema !== void 0 ? { answerSchema: record.answerSchema } : {}
+    };
+  });
+}
+function renderTraceQuestionPrompt(question) {
+  return `${ASK_QUESTION_HEADER}${QUESTION_LABEL}${question}`;
+}
+function renderTraceQuestionInstructions(question) {
+  const rules = question.answerSchema ? `${ASK_RULES}
+${ANSWER_SCHEMA_RULE}` : ASK_RULES;
+  return [
+    rules,
+    question.instructions ? `QUESTION GUIDANCE:
+${question.instructions}` : "",
+    question.answerSchema ? `ANSWER SCHEMA:
+${JSON.stringify(question.answerSchema)}` : ""
+  ].filter(Boolean).join("\n\n");
+}
+function describeTraces(spans) {
+  const { sessionByTrace } = indexSessionIdsByTrace(spans);
+  const byTrace = /* @__PURE__ */ new Map();
+  for (const span of spans) {
+    const entry = byTrace.get(span.trace_id) ?? { count: 0, start: Infinity, end: -Infinity, root: null };
+    entry.count += 1;
+    const start = Date.parse(span.start_time);
+    const end = Date.parse(span.end_time);
+    if (Number.isFinite(start)) entry.start = Math.min(entry.start, start);
+    if (Number.isFinite(end)) entry.end = Math.max(entry.end, end);
+    if (span.parent_span_id === null && entry.root === null) entry.root = span.name;
+    byTrace.set(span.trace_id, entry);
+  }
+  return [...byTrace].map(([traceId, entry]) => ({
+    traceId,
+    sessionId: sessionByTrace.get(traceId) ?? null,
+    spanCount: entry.count,
+    startTime: Number.isFinite(entry.start) ? new Date(entry.start).toISOString() : null,
+    endTime: Number.isFinite(entry.end) ? new Date(entry.end).toISOString() : null,
+    rootSpan: entry.root
+  }));
+}
+function preparedContext(traces, sheet) {
+  const list = JSON.stringify({
+    traces: traces.slice(0, MAX_CONTEXT_TRACES).map((trace) => ({
+      trace_id: trace.traceId,
+      session_id: trace.sessionId,
+      spans: trace.spanCount,
+      start: trace.startTime,
+      end: trace.endTime,
+      root: trace.rootSpan
+    })),
+    omitted_traces: Math.max(0, traces.length - MAX_CONTEXT_TRACES)
+  });
+  return sheet ? `${list}
+
+${sheet}` : list;
+}
+function createTraceQuestionCorpus() {
+  const chunks = [];
+  const traces = [];
+  const facts = createSessionFactsReportBuilder();
+  let spanCount = 0;
+  return {
+    add(spans) {
+      if (spans.length === 0) return;
+      spanCount += spans.length;
+      chunks.push(exportBytes(spans));
+      appendAll(traces, describeTraces(spans));
+      facts.add(spans);
+    },
+    finish() {
+      const store = openAgenticTraceStore(chunks.length === 1 ? chunks[0] : Buffer.concat(chunks));
+      chunks.length = 0;
+      const report = facts.build();
+      return {
+        store,
+        traces,
+        context: preparedContext(traces, report.sessions.length === 0 ? void 0 : renderSessionFactsContext(report)),
+        spanCount
+      };
+    }
+  };
+}
+var TRACE_URI = /trace:\/\/[^\s/"'`<>()[\]{}]+\/span\/[^\s/"'`<>()[\]{},;]+/g;
+var TRAILING_PROSE = /[.,:;!?*_~]+$/;
+function traceCitationsInText(text) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const match of text.matchAll(TRACE_URI)) {
+    const uri = match[0].replace(TRAILING_PROSE, "");
+    if (seen.has(uri)) continue;
+    seen.add(uri);
+    const parts = /^trace:\/\/([^/]+)\/span\/([^/]+)$/.exec(uri);
+    let traceId = null;
+    let spanId = null;
+    if (parts) {
+      try {
+        traceId = decodeURIComponent(parts[1]);
+        spanId = decodeURIComponent(parts[2]);
+      } catch {
+        traceId = null;
+        spanId = null;
+      }
+    }
+    out.push({ uri, traceId, spanId });
+  }
+  return out;
+}
+async function verifyCitations(text, store) {
+  const citations = traceCitationsInText(text);
+  const wanted = /* @__PURE__ */ new Map();
+  for (const citation of citations) {
+    if (!citation.traceId || !citation.spanId) continue;
+    const spans = wanted.get(citation.traceId) ?? /* @__PURE__ */ new Set();
+    spans.add(citation.spanId);
+    wanted.set(citation.traceId, spans);
+  }
+  const found = /* @__PURE__ */ new Map();
+  for (const [traceId, spanIds] of wanted) {
+    const existing = await store.hasSpans({ trace_id: traceId, span_ids: [...spanIds] });
+    found.set(traceId, new Set(existing));
+  }
+  return citations.map((citation) => ({
+    ...citation,
+    resolved: Boolean(citation.traceId && citation.spanId && found.get(citation.traceId)?.has(citation.spanId))
+  }));
+}
+function isBudgetRefusal(error) {
+  if (error instanceof CostCeilingReachedError) return true;
+  const message = error instanceof Error ? error.message : String(error);
+  return /would exceed ceiling|model cost limit reached/.test(message);
+}
+function ledgerIsExhausted(ledger, budgetUsd, floorUsd) {
+  if (budgetUsd === void 0 || floorUsd === void 0) return false;
+  const settled = ledger.summary({ channel: "analyst" }).totalCostUsd;
+  return Number.isFinite(settled) && budgetUsd - settled < floorUsd;
+}
+var ENGINE_NO_ANSWER = /returned no answer/;
+function questionFailureKind(error, state) {
+  if (state.aborted) return "aborted";
+  if (isBudgetRefusal(error)) return "budget-refused";
+  const message = errorMessage(error);
+  if (isBridgeMismatchError(message)) return "error";
+  if (ENGINE_NO_ANSWER.test(message)) return "no-answer";
+  return state.ledgerExhausted ? "budget-refused" : "error";
+}
+function errorMessage(error) {
+  return error instanceof Error ? `${error.constructor.name}: ${error.message}` : String(error);
+}
+function engineCallReservationFloorUsd(engine) {
+  const config = engine.executionConfig;
+  const pricing = config.pricing;
+  const outputRate = pricing?.outputUsdPerMillion;
+  const maxOutput = config.max_output_tokens;
+  const maxReasoning = config.max_reasoning_tokens ?? 0;
+  if (typeof outputRate !== "number" || typeof maxOutput !== "number" || typeof maxReasoning !== "number") {
+    return void 0;
+  }
+  return (maxOutput + maxReasoning) * outputRate / 1e6;
+}
+function formatUsd(value) {
+  return `$${value < 0.01 && value > 0 ? value.toPrecision(2) : value.toFixed(2)}`;
+}
+function unrunAnswer(question, failure, model) {
+  const at = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    id: question.id,
+    question: question.question,
+    status: "failed",
+    failure,
+    answer: null,
+    citations: [],
+    findings: [],
+    rejectedFindings: {},
+    model,
+    modelCalls: null,
+    toolCalls: null,
+    usage: null,
+    startedAt: at,
+    endedAt: at,
+    latencyMs: 0
+  };
+}
+function sumOrNull(values) {
+  return values.some((value) => value === null) ? null : values.reduce((sum, value) => sum + (value ?? 0), 0);
+}
+async function runTraceQuestions(opts) {
+  if ((opts.corpus?.spanCount ?? opts.spans?.length ?? 0) === 0) throw new Error("runTraceQuestions: no spans to ask about");
+  const questions = normalizeTraceQuestions(opts.questions);
+  const concurrency = opts.concurrency ?? DEFAULT_ASK_CONCURRENCY;
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1) throw new RangeError("concurrency must be an integer >= 1");
+  const budgetUsd = opts.budgetUsd;
+  if (budgetUsd !== void 0 && (!Number.isFinite(budgetUsd) || budgetUsd <= 0)) {
+    throw new RangeError("budgetUsd must be a positive number");
+  }
+  const warnings = [];
+  const floor = engineCallReservationFloorUsd(opts.engine);
+  const effectiveConcurrency = Math.min(concurrency, questions.length);
+  if (budgetUsd !== void 0 && floor !== void 0) {
+    if (budgetUsd < floor) {
+      throw new RangeError(
+        `budget ${formatUsd(budgetUsd)} is below one model call's reservation of at least ${formatUsd(floor)} for ${opts.engine.model ?? opts.engine.id}; every question would be refused before it ran`
+      );
+    }
+    if (budgetUsd < floor * effectiveConcurrency) {
+      warnings.push(
+        `budget ${formatUsd(budgetUsd)} covers at most ${Math.floor(budgetUsd / floor)} concurrent model call(s) at ${formatUsd(floor)} reserved each; questions wait for reservations, and later calls are refused once settled spend leaves less than one reservation`
+      );
+    }
+  }
+  opts.signal?.throwIfAborted();
+  const runStarted = performance.now();
+  const generatedAt = opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const corpus = opts.corpus ?? (() => {
+    const builder = createTraceQuestionCorpus();
+    builder.add(opts.spans);
+    return builder.finish();
+  })();
+  const { store, traces, context } = corpus;
+  const runId = `traces-ask-${Date.parse(generatedAt) || Date.now()}`;
+  const ledger = new CostLedger(budgetUsd);
+  let active = 0;
+  let peakConcurrency = 0;
+  const askOne = async (question) => {
+    const startedAt = /* @__PURE__ */ new Date();
+    const started = performance.now();
+    const rejections = createFindingRejectionTally(question.id);
+    let usage = null;
+    let completed;
+    let failure;
+    const log = (msg, fields) => {
+      rejections.record(msg, fields);
+      opts.log?.(`[${question.id}] ${msg}`, fields);
+    };
+    const definition = defineTraceAnalyst({
+      // Namespaced so a question ID can never select a built-in kind's subject rules.
+      id: `ask.${question.id}`,
+      description: `traces ask question ${question.id}`,
+      area: "question",
+      version: ASK_DEFINITION_VERSION,
+      question: renderTraceQuestionPrompt(question.question),
+      instructions: renderTraceQuestionInstructions(question),
+      toolGroup: "all",
+      prepareContext: () => context,
+      ...opts.limits ? { limits: opts.limits } : {}
+    });
+    if (opts.signal?.aborted) {
+      failure = { kind: "aborted", message: "run aborted before the question started" };
+    } else {
+      active += 1;
+      peakConcurrency = Math.max(peakConcurrency, active);
+      try {
+        completed = await runTraceAnalyst({
+          definition,
+          engine: opts.engine,
+          store,
+          context: {
+            runId,
+            correlationId: `${runId}:${question.id}`,
+            costLedger: ledger,
+            costPhase: "trace-question",
+            log,
+            recordUsage: (receipt) => {
+              usage = receipt;
+            },
+            ...opts.signal ? { signal: opts.signal } : {}
+          }
+        });
+      } catch (error) {
+        failure = {
+          kind: questionFailureKind(error, {
+            aborted: opts.signal?.aborted ?? false,
+            ledgerExhausted: ledgerIsExhausted(ledger, budgetUsd, floor)
+          }),
+          message: errorMessage(error)
+        };
+      } finally {
+        active -= 1;
+      }
+    }
+    const answer = completed && completed.answer.trim() ? completed.answer : null;
+    let parsedAnswer;
+    let hasParsedAnswer = false;
+    let citations = [];
+    try {
+      if (answer !== null) {
+        citations = await verifyCitations(answer, store);
+        if (question.answerSchema) {
+          const parsed = parseJsonAnswer(answer);
+          const problems = parsed.ok ? answerSchemaErrors(parsed.value, question.answerSchema) : [parsed.error];
+          if (parsed.ok) {
+            parsedAnswer = parsed.value;
+            hasParsedAnswer = true;
+          }
+          if (problems.length > 0 && !failure) {
+            failure = { kind: "invalid-answer", message: problems.slice(0, 5).join("; ") };
+          }
+        }
+        const unresolved = citations.filter((citation) => !citation.resolved);
+        if (unresolved.length > 0 && !failure) {
+          failure = {
+            kind: "unresolved-citations",
+            message: `${unresolved.length} cited span(s) do not exist: ${unresolved.slice(0, 3).map((c) => c.uri).join(", ")}`
+          };
+        }
+      } else if (completed && !failure) {
+        failure = { kind: "no-answer", message: "the engine returned an empty answer" };
+      }
+    } catch (error) {
+      if (!failure) {
+        failure = {
+          kind: opts.signal?.aborted ? "aborted" : "error",
+          message: `checking the answer failed: ${errorMessage(error)}`
+        };
+      }
+    }
+    const endedAt = /* @__PURE__ */ new Date();
+    return {
+      id: question.id,
+      question: question.question,
+      status: failure ? "failed" : "answered",
+      ...failure ? { failure } : {},
+      answer,
+      ...hasParsedAnswer ? { parsedAnswer } : {},
+      citations,
+      findings: completed?.findings ?? [],
+      rejectedFindings: rejections.counts()[question.id] ?? {},
+      model: opts.engine.model ?? null,
+      modelCalls: completed?.modelCalls ?? null,
+      toolCalls: completed?.toolCalls ?? null,
+      usage,
+      startedAt: startedAt.toISOString(),
+      endedAt: endedAt.toISOString(),
+      latencyMs: Math.round(performance.now() - started),
+      ...completed ? { trajectory: completed.trajectory } : {}
+    };
+  };
+  const answers = new Array(questions.length);
+  let next = 0;
+  const setupTimeMs = Math.round(performance.now() - runStarted);
+  const settled = await Promise.allSettled(Array.from({ length: effectiveConcurrency }, async () => {
+    while (next < questions.length) {
+      const index = next;
+      next += 1;
+      answers[index] = await askOne(questions[index]);
+    }
+  }));
+  const failedWorker = settled.find((worker) => worker.status === "rejected");
+  const wallTimeMs = Math.round(performance.now() - runStarted);
+  if (failedWorker) {
+    const message = errorMessage(failedWorker.reason);
+    warnings.push(`the question pool stopped early: ${message}`);
+    const kind = opts.signal?.aborted ? "aborted" : "error";
+    for (const [index, question] of questions.entries()) {
+      answers[index] ??= unrunAnswer(question, { kind, message }, opts.engine.model ?? null);
+    }
+  }
+  const summary = ledger.summary({ channel: "analyst" });
+  const answered = answers.filter((answer) => answer.status === "answered").length;
+  const totals = {
+    questions: answers.length,
+    answered,
+    failed: answers.length - answered,
+    modelCalls: sumOrNull(answers.map((answer) => answer.modelCalls)),
+    toolCalls: sumOrNull(answers.map((answer) => answer.toolCalls)),
+    providerCalls: summary.totalCalls + summary.pendingCalls,
+    cost: summary.costProvenance,
+    wallTimeMs,
+    setupTimeMs,
+    questionTimeMs: answers.reduce((sum, answer) => sum + answer.latencyMs, 0),
+    peakConcurrency
+  };
+  const partial = {
+    schemaVersion: 1,
+    kind: "traces.ask",
+    generatedAt,
+    harness: opts.harness ?? "unknown",
+    engine: { id: opts.engine.id, version: opts.engine.version, model: opts.engine.model ?? null },
+    concurrency,
+    effectiveConcurrency,
+    budgetUsd: budgetUsd ?? null,
+    questionBudgetUsd: typeof opts.engine.executionConfig.max_cost_usd === "number" ? opts.engine.executionConfig.max_cost_usd : null,
+    questionTimeoutMs: typeof opts.engine.executionConfig.timeout_ms === "number" ? opts.engine.executionConfig.timeout_ms : null,
+    spanCount: corpus.spanCount,
+    traces,
+    questions: answers,
+    totals,
+    warnings,
+    ok: answered === answers.length
+  };
+  return { ...partial, report: renderTraceQuestionsReport(partial) };
+}
+function costText(cost) {
+  if (!cost) return "not captured";
+  return cost.kind === "uncaptured" ? "uncaptured" : `${formatUsd(cost.usd)} ${cost.kind}`;
+}
+function seconds(ms) {
+  return `${(ms / 1e3).toFixed(1)} s`;
+}
+function cell(value) {
+  return value.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+}
+function countText(value) {
+  return value === null ? "unknown" : String(value);
+}
+var ANSWER_SECTION_LEVEL = 2;
+function nestAnswerHeadings(text) {
+  let fence = null;
+  return text.split("\n").map((line) => {
+    const fenced = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (fenced) {
+      const marker = fenced[1][0];
+      const length = fenced[1].length;
+      if (fence === null) fence = { marker, length };
+      else if (fence.marker === marker && length >= fence.length) fence = null;
+      return line;
+    }
+    if (fence !== null) return line;
+    const heading = /^(#{1,6})(?=\s)/.exec(line);
+    if (!heading) return line;
+    const level = Math.min(6, Math.max(ANSWER_SECTION_LEVEL + 1, heading[1].length));
+    return `${"#".repeat(level)}${line.slice(heading[1].length)}`;
+  }).join("\n");
+}
+function renderTraceQuestionsReport(result) {
+  const { totals } = result;
+  const lines = ["# traces ask", ""];
+  const effective = result.effectiveConcurrency === result.concurrency ? "" : ` (${result.effectiveConcurrency} effective)`;
+  lines.push(
+    `${totals.questions} question(s) over ${result.traces.length} trace(s) (${result.spanCount} spans, ${result.harness}). Engine \`${result.engine.id}\`${result.engine.model ? `, model \`${result.engine.model}\`` : ""}; concurrency ${result.concurrency}${effective}; budget ${result.budgetUsd === null ? "uncapped" : `${formatUsd(result.budgetUsd)} shared`}${result.questionBudgetUsd === null ? "" : `, ${formatUsd(result.questionBudgetUsd)} per question`}.`
+  );
+  lines.push("");
+  lines.push(
+    `**${totals.answered} answered, ${totals.failed} failed.** Wall time ${seconds(totals.wallTimeMs)} (${seconds(totals.setupTimeMs)} of it building the trace store) against ${seconds(totals.questionTimeMs)} of question time (peak ${totals.peakConcurrency} at once). Cost ${costText(totals.cost)} over ${totals.providerCalls} provider call(s); ${countText(totals.modelCalls)} model call(s), ${countText(totals.toolCalls)} tool call(s).`
+  );
+  lines.push("");
+  for (const warning of result.warnings) {
+    lines.push(`> Warning: ${warning}`);
+    lines.push("");
+  }
+  lines.push("| ID | Status | Citations | Rejected findings | Model calls | Tool calls | Cost | Time |");
+  lines.push("|---|---|---|---|---|---|---|---|");
+  for (const answer of result.questions) {
+    const resolved = answer.citations.filter((citation) => citation.resolved).length;
+    lines.push(
+      `| \`${cell(answer.id)}\` | ${answer.status === "answered" ? "answered" : `failed: ${answer.failure?.kind}`} | ${resolved}/${answer.citations.length} resolved | ${totalFindingRejections(answer.rejectedFindings)} | ${countText(answer.modelCalls)} | ${countText(answer.toolCalls)} | ${costText(answer.usage?.cost)} | ${seconds(answer.latencyMs)} |`
+    );
+  }
+  lines.push("");
+  for (const answer of result.questions) {
+    lines.push(`## ${answer.id}: ${answer.question.replace(/\s+/g, " ").trim()}`);
+    lines.push("");
+    if (answer.failure) {
+      lines.push(`**Failed (${answer.failure.kind}):** ${answer.failure.message.trim()}`);
+      lines.push("");
+    }
+    if (answer.answer !== null) {
+      lines.push(nestAnswerHeadings(answer.answer.trim()));
+      lines.push("");
+    }
+    const notes = [];
+    const unresolved = answer.citations.filter((citation) => !citation.resolved);
+    if (answer.citations.length > 0) {
+      notes.push(
+        `- **Citations:** ${answer.citations.length - unresolved.length} of ${answer.citations.length} resolve to a span in the trace.`
+      );
+      for (const citation of unresolved) notes.push(`- **Unresolved:** ${citation.uri}`);
+    } else if (answer.answer !== null) {
+      notes.push("- **Citations:** none in the answer text.");
+    }
+    if (answer.findings.length > 0) {
+      notes.push(`- **Accepted findings:** ${answer.findings.length}`);
+      for (const finding of answer.findings.slice(0, 5)) notes.push(`  - ${finding.severity}: ${finding.claim}`);
+    }
+    const rejected = formatFindingRejections(answer.rejectedFindings);
+    if (rejected) notes.push(`- **Rejected by the evidence gate:** ${rejected}`);
+    if (notes.length > 0) lines.push(...notes, "");
+  }
+  return lines.join("\n");
+}
+async function writeTraceQuestionsArtifacts(result, outDir) {
+  const directory = resolve(outDir);
+  await mkdir(directory, { recursive: true });
+  const paths = {
+    directory,
+    result: join(directory, "answers.json"),
+    report: join(directory, "report.md")
+  };
+  const { report, ...machine } = result;
+  await Promise.all([
+    writeFile(paths.result, `${JSON.stringify(machine, null, 2)}
+`, "utf8"),
+    writeFile(paths.report, report, "utf8")
+  ]);
+  return paths;
+}
+
+export {
+  isBridgeMismatchError,
+  normalizeTraceQuestions,
+  loadTraceQuestionsFile,
+  renderTraceQuestionPrompt,
+  renderTraceQuestionInstructions,
+  createTraceQuestionCorpus,
+  traceCitationsInText,
+  engineCallReservationFloorUsd,
+  runTraceQuestions,
+  renderTraceQuestionsReport,
+  writeTraceQuestionsArtifacts
+};