agentverify 1.2.0 → 1.4.0

package/dist/cli.mjs

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 import {
   scan
-} from "./chunk-YOD7H7MC.mjs";
+} from "./chunk-XVA2M2HS.mjs";
 
 // src/cli.ts
-import { readFileSync, readdirSync, statSync } from "fs";
+import { readFileSync, readdirSync, statSync, appendFileSync, writeFileSync } from "fs";
 import { join, relative, extname } from "path";
-var VERSION = "1.2.0";
-var API_URL = "https://agentverify-api.agentverify.workers.dev/v1/scan";
+var VERSION = "1.4.0";
+var API_URL = process.env.AGENTVERIFY_API_URL ?? "https://agentverify-api.agentverify.workers.dev/v1/scan";
+var A2SPA_DOCS_URL = "https://aimodularity.com/A2SPA/docs";
+var EXIT_OK = 0;
+var EXIT_NOT_VERIFIED = 1;
+var EXIT_NOT_ASSESSED = 2;
+var EXIT_EXECUTION_ERROR = 3;
 var c = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -22,6 +27,7 @@ var c = {
 var write = (value = "") => process.stdout.write(`${value}
 `);
 var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".ts", ".py", ".json", ".yaml", ".yml", ".md", ".mjs", ".cjs"]);
+var MAX_SCAN_FILE_BYTES = 5 * 1024 * 1024;
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", "vendor", "coverage", ".cache"]);
 function collectFiles(dir) {
   const files = [];
@@ -49,8 +55,13 @@ function parseArgs(argv) {
     key: "",
     file: "",
     json: false,
+    markdown: false,
+    ci: false,
+    allowNotAssessed: false,
     help: false,
-    version: false
+    version: false,
+    policy: "",
+    summaryFile: ""
   };
   if (result.command === "--help" || result.command === "-h") {
     result.command = "";
@@ -65,6 +76,11 @@ function parseArgs(argv) {
     if (arg === "--key" || arg === "-k") result.key = args[++i] ?? "";
     else if (arg === "--file" || arg === "-f") result.file = args[++i] ?? "";
     else if (arg === "--json") result.json = true;
+    else if (arg === "--markdown") result.markdown = true;
+    else if (arg === "--ci") result.ci = true;
+    else if (arg === "--allow-not-assessed") result.allowNotAssessed = true;
+    else if (arg === "--policy") result.policy = args[++i] ?? "";
+    else if (arg === "--summary-file") result.summaryFile = args[++i] ?? "";
     else if (arg === "--help" || arg === "-h") result.help = true;
     else if (arg === "--version" || arg === "-v") result.version = true;
     else if (!arg.startsWith("-")) result.dir = arg;
@@ -88,6 +104,14 @@ ${c.bold}Options:${c.reset}
   --key, -k     API key (or set AGENTVERIFY_API_KEY env var)
   --file, -f    Scan a single file instead of a directory
   --json        Output results as JSON
+  --markdown    Output a Markdown summary
+  --ci          CI mode: concise output and non-zero exit for NOT VERIFIED
+  --allow-not-assessed
+                In CI mode, do not fail only because content is NOT_ASSESSED
+  --policy <id> Evaluate a built-in policy profile against this scan's evidence
+                in addition to the scanner's own verdict (e.g. financial-agent)
+  --summary-file <path>
+                Write results as JSON to this path (in addition to any other output)
   --version, -v Print version
   --help, -h    Show this help message
 
@@ -104,17 +128,123 @@ ${c.bold}Examples:${c.reset}
   ${c.gray}# Output as JSON (useful for CI/CD)${c.reset}
   agentverify scan . --key av_your_key --json
 
+  ${c.gray}# Markdown summary for pull requests${c.reset}
+  agentverify scan . --key av_your_key --markdown
+
+${c.bold}Exit codes (--ci):${c.reset}
+  0   All scanned files verified
+  1   NOT VERIFIED \u2014 a security/verification check failed
+  2   NOT ASSESSED \u2014 insufficient evidence for a verdict (see --allow-not-assessed)
+  3   Execution error \u2014 the scan itself could not run (bad key, network, missing file)
+
 ${c.bold}Get your API key:${c.reset}
   https://aimodularity.com/agentverify/dashboard
 
 ${c.bold}Docs:${c.reset}
   https://github.com/AI-Blockchain-Ventures/agentverify
+
+${c.bold}A2SPA docs:${c.reset}
+  ${A2SPA_DOCS_URL}
+`);
+}
+function getTopBlocker(result) {
+  return result.reportInsights?.topBlocker ?? result.findings[0]?.title ?? "No blocking finding detected";
+}
+function getFixFirst(result) {
+  const fromInsights = result.reportInsights?.fixPriority?.filter((item) => item.priority === "fix_first").map((item) => item.title) ?? [];
+  const fallback = result.findings.slice(0, 3).map((item) => item.title);
+  return (fromInsights.length ? fromInsights : fallback).slice(0, 3);
+}
+function getRelevantThreatCategories(result) {
+  return (result.threatCategories ?? []).filter((item) => item.status !== "not_assessed").slice(0, 6).map((item) => `${item.label} (${item.status.replace("_", " ")})`);
+}
+function criticalCount(result) {
+  return result.findings.filter((f) => f.severity === "critical").length;
+}
+function highCount(result) {
+  return result.findings.filter((f) => f.severity === "high").length;
+}
+function fingerprintPreview(result) {
+  const hash = result.artifactFingerprint?.artifactHash;
+  return hash ? `${hash.slice(0, 12)}\u2026` : null;
+}
+function printDetailedSummary(result, fileName) {
+  const verified = result.verdict === "VERIFIED";
+  const verdictColor = verified ? c.green : result.verdict === "NOT_ASSESSED" ? c.yellow : c.red;
+  write(`
+${c.bold}${c.cyan}Agent Verify${c.reset}`);
+  write(`${c.gray}${fileName}${c.reset}`);
+  write(`${c.bold}Score:${c.reset} ${result.riskScore}/100`);
+  write(`${c.bold}Verdict:${c.reset} ${verdictColor}${result.verdict === "NOT_VERIFIED" ? "NOT VERIFIED" : result.verdict.replace("_", " ")}${c.reset}`);
+  write(`${c.bold}Risk level:${c.reset} ${result.riskLevel}`);
+  write(`${c.bold}Confidence:${c.reset} ${result.confidence}/100`);
+  write(`${c.bold}Critical / High findings:${c.reset} ${criticalCount(result)} / ${highCount(result)}`);
+  if (result.metadata?.scannerVersion) write(`${c.bold}Ruleset version:${c.reset} ${result.metadata.scannerVersion}`);
+  if (fingerprintPreview(result)) write(`${c.bold}Artifact fingerprint:${c.reset} ${fingerprintPreview(result)}`);
+  if (result.policyProfile) write(`${c.bold}Policy (${result.policyProfile}):${c.reset} ${result.policyResult === "PASS" ? `${c.green}PASS${c.reset}` : `${c.red}FAIL${c.reset}`}`);
+  write(`${c.bold}Top blocker:${c.reset} ${getTopBlocker(result)}`);
+  write(`
+${c.bold}Fix first:${c.reset}`);
+  const fixes = getFixFirst(result);
+  if (fixes.length) fixes.forEach((item, index) => write(`  ${index + 1}. ${item}`));
+  else write(`  No blocking fixes detected. Re-scan after any material change.`);
+  if (result.reportInsights?.nextAction) write(`
+${c.bold}Next action:${c.reset} ${result.reportInsights.nextAction}`);
+  const threats = getRelevantThreatCategories(result);
+  if (threats.length) {
+    write(`
+${c.bold}Threat categories:${c.reset}`);
+    threats.forEach((item) => write(`  - ${item}`));
+  }
+  if (result.saved && result.reportId) write(`${c.bold}View report:${c.reset} https://aimodularity.com/agentverify/report/?id=${result.reportId}`);
+  write(`${c.bold}A2SPA docs:${c.reset} ${A2SPA_DOCS_URL}`);
+  write(`${c.gray}Re-scan:${c.reset} agentverify scan --file ${fileName} --key $AGENTVERIFY_API_KEY
+`);
+}
+function markdownSummary(results, summary) {
+  const lines = ["# Agent Verify", "", `Files scanned: ${summary.total}`, `Verified: ${summary.verified}`, `Not verified: ${summary.notVerified}`, `Not assessed: ${summary.notAssessed}`, `Errors: ${summary.errors}`, ""];
+  for (const item of results) {
+    if (!item.result) {
+      lines.push(`## ${item.file}`, "", `Error: ${item.error ?? "Unknown error"}`, "");
+      continue;
+    }
+    lines.push(`## ${item.file}`, "", `Score: ${item.result.riskScore}/100`, `Verdict: ${item.result.verdict === "NOT_VERIFIED" ? "NOT VERIFIED" : item.result.verdict.replace("_", " ")}`, `Risk level: ${item.result.riskLevel}`, `Critical / High findings: ${criticalCount(item.result)} / ${highCount(item.result)}`);
+    if (item.result.metadata?.scannerVersion) lines.push(`Ruleset version: ${item.result.metadata.scannerVersion}`);
+    if (fingerprintPreview(item.result)) lines.push(`Artifact fingerprint: \`${fingerprintPreview(item.result)}\``);
+    if (item.result.policyProfile) lines.push(`Policy (${item.result.policyProfile}): ${item.result.policyResult}`);
+    lines.push(`Top blocker: ${getTopBlocker(item.result)}`, "");
+    const fixes = getFixFirst(item.result);
+    if (fixes.length) lines.push("Fix first:", ...fixes.map((fix, index) => `${index + 1}. ${fix}`), "");
+    const threats = getRelevantThreatCategories(item.result);
+    if (threats.length) lines.push("Threat categories:", ...threats.map((threat) => `- ${threat}`), "");
+    if (item.result.reportId) lines.push(`Report: https://aimodularity.com/agentverify/report/?id=${item.result.reportId}`, "");
+  }
+  lines.push(`A2SPA docs: ${A2SPA_DOCS_URL}`);
+  return lines.join("\n");
+}
+function writeGithubJobSummary(results, summary) {
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (!summaryPath) return;
+  try {
+    appendFileSync(summaryPath, `${markdownSummary(results, summary)}
 `);
+  } catch (e) {
+    console.error(`Warning: could not write GitHub job summary: ${e instanceof Error ? e.message : e}`);
+  }
+}
+function writeSummaryFile(path, results, summary) {
+  if (!path) return;
+  try {
+    writeFileSync(path, JSON.stringify({ results, summary }, null, 2));
+  } catch (e) {
+    console.error(`Warning: could not write summary file: ${e instanceof Error ? e.message : e}`);
+  }
 }
 function printVerdict(result, fileName) {
   const verified = result.verdict === "VERIFIED";
-  const icon = verified ? `${c.green}\u2713${c.reset}` : `${c.red}\u2717${c.reset}`;
-  const verdict = verified ? `${c.green}VERIFIED${c.reset}    ` : `${c.red}NOT VERIFIED${c.reset}`;
+  const notAssessed = result.verdict === "NOT_ASSESSED";
+  const icon = verified ? `${c.green}\u2713${c.reset}` : notAssessed ? `${c.yellow}\u26A0${c.reset}` : `${c.red}\u2717${c.reset}`;
+  const verdict = verified ? `${c.green}VERIFIED${c.reset}    ` : notAssessed ? `${c.yellow}NOT ASSESSED${c.reset}` : `${c.red}NOT VERIFIED${c.reset}`;
   const score = verified ? `${c.green}${result.riskScore}/100${c.reset}` : result.riskScore >= 50 ? `${c.yellow}${result.riskScore}/100${c.reset}` : `${c.red}${result.riskScore}/100${c.reset}`;
   const findings = result.findings.length > 0 ? `${c.gray}\u2014 ${result.findings.length} finding${result.findings.length === 1 ? "" : "s"}${c.reset}` : "";
   const name = fileName.padEnd(30);
@@ -128,20 +258,23 @@ async function runScan(args) {
     console.error(`
 ${c.red}Error:${c.reset} API key required
 `);
-    console.error(`  Set with --key av_your_key or AGENTVERIFY_API_KEY env var`);
-    console.error(`  Get your key at https://aimodularity.com/agentverify/dashboard
+    console.error(`  Set with --key av_your_key or AGENTVERIFY_API_KEY env var.`);
+    console.error(`  Get your key at https://aimodularity.com/agentverify/dashboard/`);
+    console.error(`  Example: AGENTVERIFY_API_KEY=av_your_key agentverify scan .
 `);
-    process.exit(1);
+    process.exit(EXIT_EXECUTION_ERROR);
   }
   let files = [];
   if (args.file) {
     files = [args.file];
   } else {
     const dir = args.dir;
-    write(`
+    if (!args.markdown && !args.json) {
+      write(`
 ${c.bold}Agent Verify${c.reset} ${c.gray}v${VERSION}${c.reset}`);
-    write(`${c.gray}Scanning ${dir}...${c.reset}
+      write(`${c.gray}Scanning ${dir}...${c.reset}
 `);
+    }
     files = collectFiles(dir);
     if (files.length === 0) {
       write(`${c.yellow}No agent files found in ${dir}${c.reset}`);
@@ -153,16 +286,21 @@ ${c.bold}Agent Verify${c.reset} ${c.gray}v${VERSION}${c.reset}`);
   const jsonResults = [];
   let verified = 0;
   let notVerified = 0;
+  let notAssessed = 0;
   let errors = 0;
   const CONCURRENCY = 3;
   for (let i = 0; i < files.length; i += CONCURRENCY) {
     const batch = files.slice(i, i + CONCURRENCY);
     const batchResults = await Promise.allSettled(
       batch.map(async (filePath) => {
+        const fileStat = statSync(filePath);
+        if (fileStat.size > MAX_SCAN_FILE_BYTES) {
+          throw new Error(`File is ${(fileStat.size / 1024 / 1024).toFixed(1)}MB, over the ${MAX_SCAN_FILE_BYTES / 1024 / 1024}MB scan limit \u2014 skipped`);
+        }
         const content = readFileSync(filePath, "utf-8");
         const relPath = relative(args.dir === "." ? process.cwd() : args.dir, filePath);
         const result = await scan(
-          { content, fileName: relPath },
+          { content, fileName: relPath, policyId: args.policy || void 0 },
           { apiKey: args.key, apiUrl: API_URL }
         );
         return { filePath, relPath, result };
@@ -172,9 +310,13 @@ ${c.bold}Agent Verify${c.reset} ${c.gray}v${VERSION}${c.reset}`);
       const outcome = batchResults[j];
       if (outcome.status === "fulfilled") {
         const { relPath, result } = outcome.value;
-        if (!args.json) printVerdict(result, relPath);
+        if (!args.json && !args.markdown) {
+          if (args.file && !args.ci) printDetailedSummary(result, relPath);
+          else printVerdict(result, relPath);
+        }
         jsonResults.push({ file: relPath, result, error: null });
         if (result.verdict === "VERIFIED") verified++;
+        else if (result.verdict === "NOT_ASSESSED") notAssessed++;
         else notVerified++;
       } else {
         const filePath = batch[j];
@@ -188,32 +330,58 @@ ${c.bold}Agent Verify${c.reset} ${c.gray}v${VERSION}${c.reset}`);
       }
     }
   }
+  const summary = { total: files.length, verified, notVerified, notAssessed, errors };
+  writeGithubJobSummary(jsonResults, summary);
+  writeSummaryFile(args.summaryFile, jsonResults, summary);
   if (args.json) {
-    write(JSON.stringify({ results: jsonResults, summary: { total: files.length, verified, notVerified, errors } }, null, 2));
+    write(JSON.stringify({ results: jsonResults, summary }, null, 2));
+    if (errors > 0) process.exit(EXIT_EXECUTION_ERROR);
+    if (args.ci) {
+      if (notVerified > 0) process.exit(EXIT_NOT_VERIFIED);
+      if (notAssessed > 0 && !args.allowNotAssessed) process.exit(EXIT_NOT_ASSESSED);
+    }
     return;
   }
+  if (args.markdown) {
+    write(markdownSummary(jsonResults, summary));
+    if (errors > 0) process.exit(EXIT_EXECUTION_ERROR);
+    if (args.ci) {
+      if (notVerified > 0) process.exit(EXIT_NOT_VERIFIED);
+      if (notAssessed > 0 && !args.allowNotAssessed) process.exit(EXIT_NOT_ASSESSED);
+    }
+    return;
+  }
+  const savedReports = jsonResults.filter((item) => item.result?.saved && item.result.reportId).length;
   write(`
 ${c.gray}${"\u2500".repeat(60)}${c.reset}`);
   write(`${c.bold}Agent Verify Scan Complete${c.reset}`);
   write(`${c.gray}Files scanned:${c.reset}   ${files.length}`);
   write(`${c.green}Verified:${c.reset}        ${verified}`);
   if (notVerified > 0) write(`${c.red}Not Verified:${c.reset}    ${notVerified}`);
+  if (notAssessed > 0) write(`${c.yellow}Not Assessed:${c.reset}    ${notAssessed}`);
   if (errors > 0) write(`${c.yellow}Errors:${c.reset}          ${errors}`);
   write(`${c.gray}${"\u2500".repeat(60)}${c.reset}`);
-  write(`
-${c.gray}View reports: https://aimodularity.com/agentverify/dashboard${c.reset}
+  if (savedReports > 0) write(`
+${c.gray}Saved CLI reports appear in your dashboard: https://aimodularity.com/agentverify/dashboard/${c.reset}`);
+  else write(`
+${c.gray}No dashboard report was saved. Check API key access and retry if you need dashboard sync.${c.reset}`);
+  write(`${c.gray}A2SPA docs: ${A2SPA_DOCS_URL}${c.reset}
 `);
-  if (notVerified > 0) process.exit(1);
+  if (errors > 0) process.exit(EXIT_EXECUTION_ERROR);
+  if (args.ci) {
+    if (notVerified > 0) process.exit(EXIT_NOT_VERIFIED);
+    if (notAssessed > 0 && !args.allowNotAssessed) process.exit(EXIT_NOT_ASSESSED);
+  }
 }
 async function main() {
   const args = parseArgs(process.argv);
   if (args.version) {
     write(`agentverify v${VERSION}`);
-    process.exit(0);
+    process.exit(EXIT_OK);
   }
   if (args.help || !args.command) {
     printHelp();
-    process.exit(0);
+    process.exit(EXIT_OK);
   }
   if (args.command === "scan") {
     await runScan(args);
@@ -222,11 +390,11 @@ async function main() {
 ${c.red}Unknown command: ${args.command}${c.reset}`);
     console.error(`Run ${c.cyan}agentverify --help${c.reset} for usage
 `);
-    process.exit(1);
+    process.exit(EXIT_EXECUTION_ERROR);
   }
 }
 main().catch((err) => {
   console.error(`
 ${c.red}Fatal error:${c.reset}`, err instanceof Error ? err.message : err);
-  process.exit(1);
+  process.exit(EXIT_EXECUTION_ERROR);
 });

package/dist/sdk.d.mts

@@ -2,25 +2,133 @@ interface ScanInput {
     content: string;
     fileName?: string;
     platform?: string;
+    /** One of the built-in policy profile ids (e.g. "financial-agent") — evaluated server-side against this scan's evidence, in addition to (never instead of) the scanner's own verdict. */
+    policyId?: string;
+}
+interface ArtifactFingerprint {
+    artifactHash: string;
+    artifactHashAlgorithm: string;
+    artifactFingerprintVersion: string;
+}
+interface ReportIntegrity {
+    reportHash: string;
+    algorithm: string;
+    schemaVersion: string;
+    scannerVersion: string;
+    scanId: string;
+    timestamp: string;
+}
+interface SignedAttestation {
+    payload: Record<string, unknown>;
+    signature: string;
+    algorithm: string;
+    publicKey: Record<string, unknown>;
+}
+type Verdict = 'VERIFIED' | 'NOT_VERIFIED' | 'NOT_ASSESSED';
+type RiskLevel = 'Low Risk' | 'Moderate Risk' | 'High Risk';
+type Category = 'A' | 'B';
+type Severity = 'critical' | 'high' | 'medium' | 'low';
+type ThreatCategoryStatus = 'detected' | 'possible' | 'missing_evidence' | 'not_assessed';
+interface ThreatCategoryAssessment {
+    id: string;
+    label: string;
+    status: ThreatCategoryStatus;
+    severity: Severity;
+    whatItMeans: string;
+    evidencePattern: string;
+    whyItMatters: string;
+    recommendedFix: string;
+    a2spaImpact: string;
 }
 interface Finding {
+    id: string;
+    code: string;
     title: string;
-    category: 'A' | 'B';
-    severity: 'critical' | 'high' | 'medium' | 'low';
+    category: Category;
+    severity: Severity;
     whatIsWrong: string;
     whyItMatters: string;
-    recommendedFix: string;
     evidence?: string;
+    recommendedFix: string;
+    fixCode?: string;
+    quickFix?: string;
+    compliance?: {
+        owasp?: string[];
+        nist?: string[];
+        soc2?: string[];
+    };
+}
+interface RuntimeBOM {
+    detectedLanguage: string;
+    detectedFramework: string | null;
+    detectedPlatform: string | null;
+    agentName: string | null;
+    toolAccessLevel: 'Restricted' | 'Unrestricted' | 'Unknown';
+    credentialExposure: 'Detected' | 'Not Detected';
+    memoryPersistence: 'Bounded' | 'Unbounded' | 'Unknown';
+    auditLogging: 'Present' | 'Absent' | 'Unknown';
+    humanGates: 'Present' | 'Absent' | 'Unknown';
+    rateLimiting: 'Present' | 'Absent' | 'Unknown';
+    promptInjectionSurface: 'Detected' | 'Not Detected' | 'Unknown';
+    delegationScope: 'Scoped' | 'Unscoped' | 'Unknown';
+}
+interface CategoryScore {
+    category: Category;
+    label: string;
+    score: number;
+    maxScore: number;
+    findingCount: number;
+}
+interface FixPriorityItem {
+    code: string;
+    title: string;
+    severity: Severity;
+    priority: 'fix_first' | 'fix_next' | 'nice_to_have';
+    reason: string;
+}
+interface ReportInsights {
+    executionReadinessScore: number;
+    a2spaReadinessScore: number;
+    remediationProgressScore: number;
+    topBlocker: string | null;
+    nextAction: string;
+    scoreExplanation: string[];
+    improvesScore: string[];
+    verificationBlockers: string[];
+    fixPriority: FixPriorityItem[];
 }
 interface ScanResult {
-    verdict: 'VERIFIED' | 'NOT VERIFIED';
+    schemaVersion: '1.3.0';
+    reportId: string;
+    verdict: Verdict;
     riskScore: number;
-    riskLevel: 'Low Risk' | 'Moderate Risk' | 'High Risk';
+    riskLevel: RiskLevel;
+    confidence: number;
+    optimizationScore: number;
+    reportInsights?: ReportInsights;
+    threatCategories?: ThreatCategoryAssessment[];
     findings: Finding[];
-    reportId: string;
-    scannedAt: string;
+    categoryScores: CategoryScore[];
+    bom: RuntimeBOM;
+    metadata: {
+        schemaVersion: '1.3.0';
+        scannerVersion: string;
+        fileName: string;
+        fileSize: number;
+        scannedAt: string;
+        detectedLanguage: string;
+        detectedFramework: string | null;
+        selectedPlatform: string | null;
+        agentName: string | null;
+        scanDuration: number;
+    };
     saved: boolean;
-    reportUrl?: string;
+    reportUrl?: string | null;
+    artifactFingerprint?: ArtifactFingerprint;
+    reportIntegrity?: ReportIntegrity;
+    policyProfile?: string | null;
+    policyResult?: string | null;
+    attestation?: SignedAttestation | null;
 }
 interface ScanOptions {
     apiKey: string;
@@ -39,7 +147,7 @@ interface ScanOptions {
  *   { apiKey: process.env.AGENTVERIFY_API_KEY }
  * )
  *
- * result.verdict    // 'VERIFIED' | 'NOT VERIFIED'
+ * result.verdict    // 'VERIFIED' | 'NOT_VERIFIED' | 'NOT_ASSESSED'
  * result.riskScore  // 0-100
  * result.findings   // Array of findings
  */

package/dist/sdk.d.ts

@@ -2,25 +2,133 @@ interface ScanInput {
     content: string;
     fileName?: string;
     platform?: string;
+    /** One of the built-in policy profile ids (e.g. "financial-agent") — evaluated server-side against this scan's evidence, in addition to (never instead of) the scanner's own verdict. */
+    policyId?: string;
+}
+interface ArtifactFingerprint {
+    artifactHash: string;
+    artifactHashAlgorithm: string;
+    artifactFingerprintVersion: string;
+}
+interface ReportIntegrity {
+    reportHash: string;
+    algorithm: string;
+    schemaVersion: string;
+    scannerVersion: string;
+    scanId: string;
+    timestamp: string;
+}
+interface SignedAttestation {
+    payload: Record<string, unknown>;
+    signature: string;
+    algorithm: string;
+    publicKey: Record<string, unknown>;
+}
+type Verdict = 'VERIFIED' | 'NOT_VERIFIED' | 'NOT_ASSESSED';
+type RiskLevel = 'Low Risk' | 'Moderate Risk' | 'High Risk';
+type Category = 'A' | 'B';
+type Severity = 'critical' | 'high' | 'medium' | 'low';
+type ThreatCategoryStatus = 'detected' | 'possible' | 'missing_evidence' | 'not_assessed';
+interface ThreatCategoryAssessment {
+    id: string;
+    label: string;
+    status: ThreatCategoryStatus;
+    severity: Severity;
+    whatItMeans: string;
+    evidencePattern: string;
+    whyItMatters: string;
+    recommendedFix: string;
+    a2spaImpact: string;
 }
 interface Finding {
+    id: string;
+    code: string;
     title: string;
-    category: 'A' | 'B';
-    severity: 'critical' | 'high' | 'medium' | 'low';
+    category: Category;
+    severity: Severity;
     whatIsWrong: string;
     whyItMatters: string;
-    recommendedFix: string;
     evidence?: string;
+    recommendedFix: string;
+    fixCode?: string;
+    quickFix?: string;
+    compliance?: {
+        owasp?: string[];
+        nist?: string[];
+        soc2?: string[];
+    };
+}
+interface RuntimeBOM {
+    detectedLanguage: string;
+    detectedFramework: string | null;
+    detectedPlatform: string | null;
+    agentName: string | null;
+    toolAccessLevel: 'Restricted' | 'Unrestricted' | 'Unknown';
+    credentialExposure: 'Detected' | 'Not Detected';
+    memoryPersistence: 'Bounded' | 'Unbounded' | 'Unknown';
+    auditLogging: 'Present' | 'Absent' | 'Unknown';
+    humanGates: 'Present' | 'Absent' | 'Unknown';
+    rateLimiting: 'Present' | 'Absent' | 'Unknown';
+    promptInjectionSurface: 'Detected' | 'Not Detected' | 'Unknown';
+    delegationScope: 'Scoped' | 'Unscoped' | 'Unknown';
+}
+interface CategoryScore {
+    category: Category;
+    label: string;
+    score: number;
+    maxScore: number;
+    findingCount: number;
+}
+interface FixPriorityItem {
+    code: string;
+    title: string;
+    severity: Severity;
+    priority: 'fix_first' | 'fix_next' | 'nice_to_have';
+    reason: string;
+}
+interface ReportInsights {
+    executionReadinessScore: number;
+    a2spaReadinessScore: number;
+    remediationProgressScore: number;
+    topBlocker: string | null;
+    nextAction: string;
+    scoreExplanation: string[];
+    improvesScore: string[];
+    verificationBlockers: string[];
+    fixPriority: FixPriorityItem[];
 }
 interface ScanResult {
-    verdict: 'VERIFIED' | 'NOT VERIFIED';
+    schemaVersion: '1.3.0';
+    reportId: string;
+    verdict: Verdict;
     riskScore: number;
-    riskLevel: 'Low Risk' | 'Moderate Risk' | 'High Risk';
+    riskLevel: RiskLevel;
+    confidence: number;
+    optimizationScore: number;
+    reportInsights?: ReportInsights;
+    threatCategories?: ThreatCategoryAssessment[];
     findings: Finding[];
-    reportId: string;
-    scannedAt: string;
+    categoryScores: CategoryScore[];
+    bom: RuntimeBOM;
+    metadata: {
+        schemaVersion: '1.3.0';
+        scannerVersion: string;
+        fileName: string;
+        fileSize: number;
+        scannedAt: string;
+        detectedLanguage: string;
+        detectedFramework: string | null;
+        selectedPlatform: string | null;
+        agentName: string | null;
+        scanDuration: number;
+    };
     saved: boolean;
-    reportUrl?: string;
+    reportUrl?: string | null;
+    artifactFingerprint?: ArtifactFingerprint;
+    reportIntegrity?: ReportIntegrity;
+    policyProfile?: string | null;
+    policyResult?: string | null;
+    attestation?: SignedAttestation | null;
 }
 interface ScanOptions {
     apiKey: string;
@@ -39,7 +147,7 @@ interface ScanOptions {
  *   { apiKey: process.env.AGENTVERIFY_API_KEY }
  * )
  *
- * result.verdict    // 'VERIFIED' | 'NOT VERIFIED'
+ * result.verdict    // 'VERIFIED' | 'NOT_VERIFIED' | 'NOT_ASSESSED'
  * result.riskScore  // 0-100
  * result.findings   // Array of findings
  */