@citeark/agent 0.3.20

package/src/evidence/registry.mjs

@@ -0,0 +1,147 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { executionContractMeasurements } from "../contracts/execution-contract.mjs";
+import { CiteArkError, pathExists, safeRelativePath, sha256File, writeJson } from "../util.mjs";
+import { getEvidenceParser } from "./parser-registry.mjs";
+
+export {
+  listEvidenceParsers,
+  registerEvidenceParser,
+  validateEvidenceParserDescriptor,
+} from "./parser-registry.mjs";
+
+export async function parseContractEvidence({ contract, outputDirectory, metricsPath, parsedAt, result }) {
+  const bindings = executionContractMeasurements(contract);
+  const measurements = await Promise.all(bindings.map((binding) =>
+    parseMeasurementEvidence({ contract, binding, outputDirectory, parsedAt, result }),
+  ));
+  const metrics = {
+    schemaVersion: "1.0",
+    contractDigest: contract.contractDigest,
+    ...(contract.executionPlan ? { executionPlanDigest: contract.executionPlan.digest } : {}),
+    measurements,
+    parsedAt: parsedAt ?? new Date().toISOString(),
+  };
+  if (metricsPath) await writeJson(metricsPath, metrics);
+  return metrics;
+}
+
+async function parseMeasurementEvidence({ contract, binding, outputDirectory, parsedAt, result }) {
+  const descriptor = binding.parser;
+  const parser = getEvidenceParser(descriptor);
+  if (!parser) throw new CiteArkError(`没有注册证据解析器：${descriptor.id}@${descriptor.version}`);
+  if (!safeRelativePath(descriptor.evidencePath)) throw new CiteArkError("parser.evidencePath 不是安全相对路径");
+  const evidencePath = path.resolve(outputDirectory, descriptor.evidencePath);
+  const allowUnavailableMetric = result?.execution?.status === "failed" || result?.execution?.status === "partial";
+  const resultProvided = result !== undefined && result !== null;
+  const evidencePromoted = Array.isArray(result?.evidence)
+    && result.evidence.some((item) => item?.path === descriptor.evidencePath);
+  if (resultProvided && !evidencePromoted) {
+    const reason = `The submitted result did not promote parser evidence at ${descriptor.evidencePath}`;
+    if (!allowUnavailableMetric) throw new CiteArkError(reason);
+    return await unavailableMetrics({
+      contract,
+      binding,
+      descriptor,
+      parser,
+      parsedAt,
+      result,
+      reason,
+    });
+  }
+  if (!(await pathExists(evidencePath))) {
+    if (!allowUnavailableMetric) throw new CiteArkError(`解析器证据不存在：${descriptor.evidencePath}`);
+    return await unavailableMetrics({
+      contract,
+      binding,
+      descriptor,
+      parser,
+      parsedAt,
+      result,
+      reason: `The execution did not produce parser evidence at ${descriptor.evidencePath}`,
+    });
+  }
+  const [text, stat, digest] = await Promise.all([
+    readFile(evidencePath, "utf8"),
+    lstat(evidencePath),
+    sha256File(evidencePath),
+  ]);
+  let parsed;
+  try {
+    parsed = parser.parse(text, descriptor.config ?? {});
+  } catch (error) {
+    if (!allowUnavailableMetric) throw error;
+    return await unavailableMetrics({
+      contract,
+      binding,
+      descriptor,
+      parser,
+      parsedAt,
+      result,
+      sourceEvidence: { path: descriptor.evidencePath, sha256: digest, size: stat.size },
+      reason: `The preserved parser evidence did not contain a trustworthy metric: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+  if (parsed.primary.metric !== binding.metric || parsed.primary.unit !== binding.unit) {
+    throw new CiteArkError("解析器主指标与 execution contract 不一致");
+  }
+  const metrics = {
+    schemaVersion: "0.1",
+    contractDigest: contract.contractDigest,
+    measurementId: binding.measurementId,
+    parser: { id: parser.id, version: parser.version, config: descriptor.config ?? {} },
+    sourceEvidence: {
+      path: descriptor.evidencePath,
+      sha256: digest,
+      size: stat.size,
+      producer: "execution-sandbox",
+      trust: "agent-produced-contract-pinned-input",
+    },
+    observations: parsed.observations,
+    primary: parsed.primary,
+    checks: parsed.checks ?? [],
+    availability: {
+      status: "available",
+      executionStatus: result?.execution?.status ?? "unknown",
+      reason: null,
+    },
+    parsedAt: parsedAt ?? new Date().toISOString(),
+  };
+  return metrics;
+}
+
+async function unavailableMetrics({
+  contract,
+  binding,
+  descriptor,
+  parser,
+  parsedAt,
+  result,
+  sourceEvidence = null,
+  reason,
+}) {
+  const metrics = {
+    schemaVersion: "0.1",
+    contractDigest: contract.contractDigest,
+    measurementId: binding.measurementId,
+    parser: { id: parser.id, version: parser.version, config: descriptor.config ?? {} },
+    sourceEvidence,
+    observations: [],
+    primary: null,
+    checks: [{
+      name: "metric_available",
+      status: "failed",
+      required: false,
+      description: reason,
+    }],
+    availability: {
+      status: "unavailable",
+      executionStatus: result?.execution?.status ?? "unknown",
+      reason,
+      failure: result?.execution?.failure ?? null,
+    },
+    parsedAt: parsedAt ?? new Date().toISOString(),
+  };
+  return metrics;
+}

package/src/execution/runner-audit.mjs

@@ -0,0 +1,473 @@
+import { createHash } from "node:crypto";
+import { appendFile, lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { redactString } from "../cap/redaction.mjs";
+import {
+  pathExists,
+  readJson,
+  sha256File,
+  sha256Value,
+  writeJson,
+} from "../util.mjs";
+
+const RUNNER_EVENTS = "runner-events.jsonl";
+const COMMAND_RECORDS = "command-records.jsonl";
+const RUNNER_AUDIT = "runner-audit.json";
+const RUNNER_BOUNDARY = "runner-boundary.json";
+
+export async function recordRunnerProcessStarted({
+  executionDirectory,
+  runId,
+  attempt,
+  executor,
+  command,
+  args,
+  workingDirectory,
+  captureBoundary,
+}) {
+  const event = {
+    schemaVersion: "0.1",
+    type: "runner.process_started",
+    eventId: `${runId}:${attempt}:${Date.now()}`,
+    runId,
+    attempt,
+    executor,
+    command,
+    args,
+    workingDirectory,
+    captureBoundary,
+    startedAt: new Date().toISOString(),
+  };
+  await appendJsonLine(path.join(executionDirectory, RUNNER_EVENTS), event);
+  return event;
+}
+
+export async function recordRunnerProcessFinished({
+  executionDirectory,
+  startedEvent,
+  exitCode,
+  signal,
+  timedOut,
+}) {
+  const finishedAt = new Date().toISOString();
+  await appendJsonLine(path.join(executionDirectory, RUNNER_EVENTS), {
+    schemaVersion: "0.1",
+    type: "runner.process_finished",
+    eventId: startedEvent.eventId,
+    runId: startedEvent.runId,
+    attempt: startedEvent.attempt,
+    executor: startedEvent.executor,
+    exitCode,
+    signal,
+    timedOut: Boolean(timedOut),
+    startedAt: startedEvent.startedAt,
+    finishedAt,
+    durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedEvent.startedAt)),
+  });
+}
+
+export async function buildRunnerAudit({ runDirectory, runtime, sandbox }) {
+  const executionDirectory = path.join(runDirectory, "execution");
+  const tracePath = path.join(executionDirectory, "trace.jsonl");
+  const stderrPath = path.join(executionDirectory, "claude-stderr.log");
+  const eventsPath = path.join(executionDirectory, RUNNER_EVENTS);
+  const recordsPath = path.join(executionDirectory, COMMAND_RECORDS);
+  const boundaryPath = path.join(executionDirectory, RUNNER_BOUNDARY);
+  const runPath = path.join(runDirectory, "run.json");
+  const run = (await pathExists(runPath)) ? await readJson(runPath) : null;
+  const trace = (await pathExists(tracePath)) ? await readFile(tracePath, "utf8") : "";
+  const commandRecords = extractRunnerCommandRecords(trace, { runtime });
+  await writeFile(
+    recordsPath,
+    commandRecords.length
+      ? `${commandRecords.map((record) => JSON.stringify(record)).join("\n")}\n`
+      : "",
+    "utf8",
+  );
+
+  if (!(await pathExists(eventsPath)) && Array.isArray(run?.attempts)) {
+    const fallback = run.attempts.flatMap((attempt) => [{
+      schemaVersion: "0.1",
+      type: "runner.process_observed",
+      eventId: `${run.runId}:${attempt.attempt}:run-record`,
+      runId: run.runId,
+      attempt: attempt.attempt,
+      executor: attempt.executor ?? sandbox ?? run.sandbox ?? "unknown",
+      startedAt: attempt.startedAt ?? null,
+      finishedAt: attempt.finishedAt ?? null,
+      exitCode: attempt.exitCode ?? null,
+      signal: attempt.signal ?? null,
+      timedOut: Boolean(attempt.timedOut),
+      captureBoundary: "out-of-sandbox-run-record",
+    }]);
+    await writeFile(
+      eventsPath,
+      fallback.length ? `${fallback.map((event) => JSON.stringify(event)).join("\n")}\n` : "",
+      "utf8",
+    );
+  }
+
+  const eventCount = await jsonLineCount(eventsPath);
+  const rawStreams = {
+    stdout: await fileDescriptor(tracePath, "execution/trace.jsonl"),
+    stderr: await fileDescriptor(stderrPath, "execution/claude-stderr.log"),
+  };
+  const companions = {
+    runnerEvents: await requiredFileDescriptor(eventsPath, `execution/${RUNNER_EVENTS}`),
+    commandRecords: await requiredFileDescriptor(recordsPath, `execution/${COMMAND_RECORDS}`),
+  };
+  const runnerBoundary = await fileDescriptor(boundaryPath, `execution/${RUNNER_BOUNDARY}`);
+  if (runnerBoundary) companions.runnerBoundary = runnerBoundary;
+  const captureBoundary = sandbox === "docker"
+    ? "host-runner-outside-agent-mounts"
+    : new Set(["gcp-batch", "autodl-pro"]).has(sandbox)
+      ? await remoteCaptureBoundary(executionDirectory, sandbox)
+      : "runner-process-stream";
+  const base = {
+    schemaVersion: "0.1",
+    kind: "citeark.runner-execution-audit",
+    runId: run?.runId ?? null,
+    runtime,
+    sandbox,
+    generatedAt: run?.finishedAt ?? new Date().toISOString(),
+    status: rawStreams.stdout && eventCount > 0 ? "complete" : "degraded",
+    captureBoundary,
+    contentPolicy: {
+      commandAndOutputRetention: "verbatim-unless-likely-secret-redacted",
+      privateReasoningRetained: false,
+      rawRuntimeStreamRetention: "digest-only",
+    },
+    rawStreams,
+    companions,
+    processEventCount: eventCount,
+    commandRecordCount: commandRecords.length,
+    completedCommandRecordCount: commandRecords.filter((record) => record.finishedAt).length,
+    commandCapture: {
+      source: "runner-captured-runtime-json-stream",
+      parser: `${runtime ?? "unknown"}-runtime-events-v0.1`,
+      recordsPath: `execution/${COMMAND_RECORDS}`,
+    },
+  };
+  const audit = { ...base, auditDigest: `sha256:${sha256Value(base)}` };
+  await writeJson(path.join(executionDirectory, RUNNER_AUDIT), audit);
+  return { audit, commandRecords };
+}
+
+export async function loadAndVerifyRunnerAudit(runDirectory) {
+  const executionDirectory = path.join(runDirectory, "execution");
+  const auditPath = path.join(executionDirectory, RUNNER_AUDIT);
+  if (!(await pathExists(auditPath))) {
+    return { audit: null, commandRecords: [], issues: ["runner-audit.json is missing"] };
+  }
+  const audit = await readJson(auditPath);
+  const { auditDigest, ...base } = audit;
+  const issues = [];
+  if (auditDigest !== `sha256:${sha256Value(base)}`) issues.push("runner audit digest mismatch");
+  for (const descriptor of Object.values(audit.companions ?? {})) {
+    if (!descriptor?.path) {
+      issues.push("runner audit companion path is missing");
+      continue;
+    }
+    const relative = descriptor.path.replace(/^execution\//, "");
+    const target = path.join(executionDirectory, relative);
+    if (!(await pathExists(target))) {
+      issues.push(`runner audit companion is missing: ${descriptor.path}`);
+      continue;
+    }
+    const stat = await lstat(target);
+    const digest = await sha256File(target);
+    if (descriptor.sha256 !== digest || descriptor.size !== stat.size) {
+      issues.push(`runner audit companion digest mismatch: ${descriptor.path}`);
+    }
+  }
+  for (const descriptor of Object.values(audit.rawStreams ?? {}).filter(Boolean)) {
+    const relative = descriptor.path.replace(/^execution\//, "");
+    const target = path.join(executionDirectory, relative);
+    if (!(await pathExists(target))) {
+      issues.push(`runner raw stream is missing: ${descriptor.path}`);
+      continue;
+    }
+    const stat = await lstat(target);
+    const digest = await sha256File(target);
+    if (descriptor.sha256 !== digest || descriptor.size !== stat.size) {
+      issues.push(`runner raw stream digest mismatch: ${descriptor.path}`);
+    }
+  }
+  const recordsPath = path.join(executionDirectory, COMMAND_RECORDS);
+  const commandRecords = await readJsonLines(recordsPath);
+  if (commandRecords.length !== audit.commandRecordCount) {
+    issues.push("runner audit command record count mismatch");
+  }
+  return { audit, commandRecords, issues };
+}
+
+export function extractRunnerCommandRecords(rawTrace, { runtime } = {}) {
+  const parsed = parseTraceLines(rawTrace);
+  const normalizedRuntime = runtime ?? detectRuntime(parsed.map((item) => item.event));
+  if (normalizedRuntime === "codex") return extractCodexCommands(parsed);
+  if (normalizedRuntime === "opencode") return extractOpenCodeCommands(parsed);
+  return extractClaudeCommands(parsed, normalizedRuntime ?? "claude-code");
+}
+
+function extractClaudeCommands(lines, runtime) {
+  const pending = new Map();
+  const records = [];
+  let attempt = 1;
+  for (const line of lines) {
+    const event = line.event;
+    if (event.type === "citeark.attempt_started" && Number.isInteger(event.attempt)) {
+      attempt = event.attempt;
+      continue;
+    }
+    const content = Array.isArray(event.message?.content) ? event.message.content : [];
+    if (event.type === "assistant") {
+      for (const item of content) {
+        if (item?.type !== "tool_use" || !shellTool(item.name)) continue;
+        const command = item.input?.command;
+        if (typeof command !== "string" || !command.trim()) continue;
+        pending.set(item.id, {
+          schemaVersion: "0.1",
+          kind: "runtime-tool-command",
+          recordId: item.id,
+          runtime,
+          attempt,
+          tool: item.name,
+          command: protectedText(command),
+          workingDirectory: stringOrNull(item.input?.cwd),
+          startedAt: timestamp(event),
+          finishedAt: null,
+          exitCode: null,
+          exitCodeSource: "unavailable",
+          status: "started",
+          stdout: protectedText(""),
+          stderr: protectedText(""),
+          sourceEventDigests: [line.sha256],
+          provenance: "runner-captured-runtime-json-stream",
+        });
+      }
+      continue;
+    }
+    if (event.type !== "user") continue;
+    for (const item of content) {
+      if (item?.type !== "tool_result") continue;
+      const record = pending.get(item.tool_use_id);
+      if (!record) continue;
+      const result = event.tool_use_result ?? {};
+      const stdout = typeof result.stdout === "string"
+        ? result.stdout
+        : typeof item.content === "string" ? item.content : "";
+      const stderr = typeof result.stderr === "string" ? result.stderr : "";
+      const explicitExit = finiteInteger(result.exitCode ?? result.exit_code);
+      const parsedExit = explicitExit ?? exitCodeFromText(item.content);
+      const isError = item.is_error === true || event.is_error === true;
+      record.finishedAt = timestamp(event);
+      record.exitCode = parsedExit ?? (isError ? null : 0);
+      record.exitCodeSource = parsedExit !== null && parsedExit !== undefined
+        ? "runtime-reported"
+        : isError ? "unavailable" : "runtime-success-status";
+      record.status = isError ? "failed" : "completed";
+      record.stdout = protectedText(stdout);
+      record.stderr = protectedText(stderr);
+      record.interrupted = result.interrupted === true;
+      record.sourceEventDigests.push(line.sha256);
+      records.push(record);
+      pending.delete(item.tool_use_id);
+    }
+  }
+  records.push(...pending.values());
+  return records;
+}
+
+function extractCodexCommands(lines) {
+  const pending = new Map();
+  const records = [];
+  let attempt = 1;
+  for (const line of lines) {
+    const event = line.event;
+    if (event.type === "citeark.attempt_started" && Number.isInteger(event.attempt)) {
+      attempt = event.attempt;
+      continue;
+    }
+    const item = event.item;
+    if (!item || item.type !== "command_execution") continue;
+    const id = item.id ?? `codex:${line.order}`;
+    if (event.type === "item.started") {
+      pending.set(id, baseCodexRecord({ item, line, attempt, id }));
+      continue;
+    }
+    if (event.type !== "item.completed") continue;
+    const record = pending.get(id) ?? baseCodexRecord({ item, line, attempt, id });
+    const exitCode = finiteInteger(item.exit_code);
+    record.finishedAt = timestamp(event);
+    record.exitCode = exitCode;
+    record.exitCodeSource = exitCode === null ? "unavailable" : "runtime-reported";
+    record.status = item.status ?? (exitCode === 0 ? "completed" : "failed");
+    record.stdout = protectedText(item.aggregated_output ?? "");
+    record.stderr = protectedText(item.stderr ?? "");
+    record.sourceEventDigests.push(line.sha256);
+    records.push(record);
+    pending.delete(id);
+  }
+  records.push(...pending.values());
+  return records;
+}
+
+function baseCodexRecord({ item, line, attempt, id }) {
+  return {
+    schemaVersion: "0.1",
+    kind: "runtime-tool-command",
+    recordId: id,
+    runtime: "codex",
+    attempt,
+    tool: "command_execution",
+    command: protectedText(item.command ?? ""),
+    workingDirectory: stringOrNull(item.cwd),
+    startedAt: timestamp(line.event),
+    finishedAt: null,
+    exitCode: null,
+    exitCodeSource: "unavailable",
+    status: "started",
+    stdout: protectedText(""),
+    stderr: protectedText(""),
+    sourceEventDigests: [line.sha256],
+    provenance: "runner-captured-runtime-json-stream",
+  };
+}
+
+function extractOpenCodeCommands(lines) {
+  const records = [];
+  let attempt = 1;
+  for (const line of lines) {
+    const event = line.event;
+    if (event.type === "citeark.attempt_started" && Number.isInteger(event.attempt)) {
+      attempt = event.attempt;
+      continue;
+    }
+    const part = event.part ?? event.item ?? event;
+    const state = part.state ?? {};
+    const tool = part.tool ?? part.name ?? event.tool;
+    const command = state.input?.command ?? part.input?.command;
+    if (!shellTool(tool) || typeof command !== "string" || !command.trim()) continue;
+    const exitCode = finiteInteger(state.metadata?.exit ?? state.metadata?.exitCode ?? part.exit_code);
+    const output = state.output ?? part.output ?? "";
+    records.push({
+      schemaVersion: "0.1",
+      kind: "runtime-tool-command",
+      recordId: part.callID ?? part.id ?? `opencode:${line.order}`,
+      runtime: "opencode",
+      attempt,
+      tool,
+      command: protectedText(command),
+      workingDirectory: stringOrNull(state.input?.cwd ?? part.input?.cwd),
+      startedAt: isoFromMilliseconds(state.time?.start) ?? timestamp(event),
+      finishedAt: isoFromMilliseconds(state.time?.end) ?? timestamp(event),
+      exitCode,
+      exitCodeSource: exitCode === null ? "unavailable" : "runtime-reported",
+      status: state.status ?? (exitCode === 0 ? "completed" : exitCode === null ? "unknown" : "failed"),
+      stdout: protectedText(typeof output === "string" ? output : JSON.stringify(output)),
+      stderr: protectedText(typeof state.metadata?.stderr === "string" ? state.metadata.stderr : ""),
+      sourceEventDigests: [line.sha256],
+      provenance: "runner-captured-runtime-json-stream",
+    });
+  }
+  return records;
+}
+
+function parseTraceLines(rawTrace) {
+  const output = [];
+  let order = 0;
+  for (const rawLine of String(rawTrace ?? "").split(/\r?\n/)) {
+    if (!rawLine.trim()) continue;
+    try {
+      const event = JSON.parse(rawLine);
+      if (event && typeof event === "object" && !Array.isArray(event)) {
+        output.push({ event, order, sha256: sha256Text(rawLine) });
+      }
+    } catch {
+      // Non-JSON runtime output remains covered by the raw stream digest.
+    }
+    order += 1;
+  }
+  return output;
+}
+
+function protectedText(value) {
+  const raw = String(value ?? "");
+  const retained = redactString(raw);
+  return {
+    text: retained,
+    rawSha256: sha256Text(raw),
+    rawBytes: Buffer.byteLength(raw),
+    retainedSha256: sha256Text(retained),
+    redactionsApplied: retained !== raw,
+  };
+}
+
+function detectRuntime(events) {
+  if (events.some((event) => event.type === "item.started" || event.type === "item.completed")) return "codex";
+  if (events.some((event) => event.part?.tool || event.part?.state)) return "opencode";
+  return "claude-code";
+}
+
+function shellTool(value) {
+  return typeof value === "string" && new Set(["Bash", "bash", "Shell", "shell", "command", "command_execution"]).has(value);
+}
+
+function timestamp(event) {
+  return stringOrNull(event.timestamp ?? event.created_at ?? event.recorded_at);
+}
+
+function stringOrNull(value) {
+  return typeof value === "string" && value.length ? value : null;
+}
+
+function finiteInteger(value) {
+  return Number.isInteger(value) ? value : null;
+}
+
+function exitCodeFromText(value) {
+  if (typeof value !== "string") return null;
+  const matched = value.match(/(?:exit(?:ed)?(?: with)? code|Exit code)\s*[:=]?\s*(\d+)/i);
+  return matched ? Number(matched[1]) : null;
+}
+
+function isoFromMilliseconds(value) {
+  return typeof value === "number" && Number.isFinite(value) ? new Date(value).toISOString() : null;
+}
+
+async function appendJsonLine(target, value) {
+  await mkdir(path.dirname(target), { recursive: true });
+  await appendFile(target, `${JSON.stringify(value)}\n`, "utf8");
+}
+
+async function jsonLineCount(target) {
+  return (await readJsonLines(target)).length;
+}
+
+async function readJsonLines(target) {
+  if (!(await pathExists(target))) return [];
+  const raw = await readFile(target, "utf8");
+  return raw.split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+}
+
+async function fileDescriptor(target, relativePath) {
+  if (!(await pathExists(target))) return null;
+  const stat = await lstat(target);
+  return { path: relativePath, size: stat.size, sha256: await sha256File(target) };
+}
+
+async function requiredFileDescriptor(target, relativePath) {
+  return await fileDescriptor(target, relativePath) ?? { path: relativePath, size: 0, sha256: sha256Text("") };
+}
+
+async function remoteCaptureBoundary(executionDirectory, sandbox) {
+  const boundaryPath = path.join(executionDirectory, RUNNER_BOUNDARY);
+  if (!(await pathExists(boundaryPath))) return `${sandbox}-supervisor-unavailable`;
+  const boundary = await readJson(boundaryPath).catch(() => null);
+  return boundary?.captureBoundary ?? `${sandbox}-supervisor-unavailable`;
+}
+
+function sha256Text(value) {
+  return createHash("sha256").update(String(value ?? ""), "utf8").digest("hex");
+}